diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index 8176602a7..322b6536a 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -8,9 +8,9 @@ body: Thanks for your interest in FastAPI! 🚀 Please follow these instructions, fill every question, and do every step. 🙏 - + I'm asking this because answering questions and solving problems in GitHub issues is what consumes most of the time. - + I end up not being able to add new features, fix bugs, review pull requests, etc. as fast as I wish because I have to spend too much time handling issues. All that, on top of all the incredible help provided by a bunch of community members, the [FastAPI Experts](https://fastapi.tiangolo.com/fastapi-people/#experts), that give a lot of their time to come here and help others. @@ -18,7 +18,7 @@ body: That's a lot of work they are doing, but if more FastAPI users came to help others like them just a little bit more, it would be much less effort for them (and you and me 😅). By asking questions in a structured way (following this) it will be much easier to help you. - + And there's a high chance that you will find the solution along the way and you won't even have to submit it and wait for an answer. 😎 As there are too many issues with questions, I'll have to close the incomplete ones. That will allow me (and others) to focus on helping people like you that follow the whole process and help us help you. 🤓 @@ -50,7 +50,7 @@ body: label: Commit to Help description: | After submitting this, I commit to one of: - + * Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there. * I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future. * Implement a Pull Request for a confirmed bug. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml index 5c76fd17e..3b16b4ad0 100644 --- a/.github/ISSUE_TEMPLATE/question.yml +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -8,9 +8,9 @@ body: Thanks for your interest in FastAPI! 🚀 Please follow these instructions, fill every question, and do every step. 🙏 - + I'm asking this because answering questions and solving problems in GitHub issues is what consumes most of the time. - + I end up not being able to add new features, fix bugs, review pull requests, etc. as fast as I wish because I have to spend too much time handling issues. All that, on top of all the incredible help provided by a bunch of community members, the [FastAPI Experts](https://fastapi.tiangolo.com/fastapi-people/#experts), that give a lot of their time to come here and help others. @@ -18,7 +18,7 @@ body: That's a lot of work they are doing, but if more FastAPI users came to help others like them just a little bit more, it would be much less effort for them (and you and me 😅). By asking questions in a structured way (following this) it will be much easier to help you. - + And there's a high chance that you will find the solution along the way and you won't even have to submit it and wait for an answer. 😎 As there are too many issues with questions, I'll have to close the incomplete ones. That will allow me (and others) to focus on helping people like you that follow the whole process and help us help you. 🤓 @@ -50,7 +50,7 @@ body: label: Commit to Help description: | After submitting this, I commit to one of: - + * Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there. * I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future. * Implement a Pull Request for a confirmed bug. diff --git a/.github/actions/comment-docs-preview-in-pr/app/main.py b/.github/actions/comment-docs-preview-in-pr/app/main.py index 3b10e0ee0..68914fdb9 100644 --- a/.github/actions/comment-docs-preview-in-pr/app/main.py +++ b/.github/actions/comment-docs-preview-in-pr/app/main.py @@ -1,7 +1,7 @@ import logging import sys from pathlib import Path -from typing import Optional +from typing import Union import httpx from github import Github @@ -14,7 +14,7 @@ github_api = "https://api.github.com" class Settings(BaseSettings): github_repository: str github_event_path: Path - github_event_name: Optional[str] = None + github_event_name: Union[str, None] = None input_token: SecretStr input_deploy_url: str @@ -42,15 +42,13 @@ if __name__ == "__main__": except ValidationError as e: logging.error(f"Error parsing event file: {e.errors()}") sys.exit(0) - use_pr: Optional[PullRequest] = None + use_pr: Union[PullRequest, None] = None for pr in repo.get_pulls(): if pr.head.sha == event.workflow_run.head_commit.id: use_pr = pr break if not use_pr: - logging.error( - f"No PR found for hash: {event.workflow_run.head_commit.id}" - ) + logging.error(f"No PR found for hash: {event.workflow_run.head_commit.id}") sys.exit(0) github_headers = { "Authorization": f"token {settings.input_token.get_secret_value()}" diff --git a/.github/actions/notify-translations/app/main.py b/.github/actions/notify-translations/app/main.py index 7d6c1a4d2..d4ba0ecfc 100644 --- a/.github/actions/notify-translations/app/main.py +++ b/.github/actions/notify-translations/app/main.py @@ -1,8 +1,8 @@ import logging +import random import time from pathlib import Path -import random -from typing import Dict, Optional +from typing import Dict, Union import yaml from github import Github @@ -18,8 +18,8 @@ class Settings(BaseSettings): github_repository: str input_token: SecretStr github_event_path: Path - github_event_name: Optional[str] = None - input_debug: Optional[bool] = False + github_event_name: Union[str, None] = None + input_debug: Union[bool, None] = False class PartialGitHubEventIssue(BaseModel): @@ -54,7 +54,7 @@ if __name__ == "__main__": ) if pr.state == "open": logging.debug(f"PR is open: {pr.number}") - label_strs = set([label.name for label in pr.get_labels()]) + label_strs = {label.name for label in pr.get_labels()} if lang_all_label in label_strs and awaiting_label in label_strs: logging.info( f"This PR seems to be a language translation and awaiting reviews: {pr.number}" diff --git a/.github/actions/notify-translations/app/translations.yml b/.github/actions/notify-translations/app/translations.yml index decd63498..d283ef9f7 100644 --- a/.github/actions/notify-translations/app/translations.yml +++ b/.github/actions/notify-translations/app/translations.yml @@ -8,8 +8,12 @@ uk: 1748 tr: 1892 fr: 1972 ko: 2017 -sq: 2041 +fa: 2041 pl: 3169 de: 3716 id: 3717 az: 3994 +nl: 4701 +uz: 4883 +sv: 5146 +he: 5157 diff --git a/.github/actions/people/app/main.py b/.github/actions/people/app/main.py index dc0bbc4c0..cdf423b97 100644 --- a/.github/actions/people/app/main.py +++ b/.github/actions/people/app/main.py @@ -4,7 +4,7 @@ import sys from collections import Counter, defaultdict from datetime import datetime, timedelta, timezone from pathlib import Path -from typing import Container, DefaultDict, Dict, List, Optional, Set +from typing import Container, DefaultDict, Dict, List, Set, Union import httpx import yaml @@ -14,7 +14,7 @@ from pydantic import BaseModel, BaseSettings, SecretStr github_graphql_url = "https://api.github.com/graphql" issues_query = """ -query Q($after: String) { +query Q($after: String) { repository(name: "fastapi", owner: "tiangolo") { issues(first: 100, after: $after) { edges { @@ -47,7 +47,7 @@ query Q($after: String) { """ prs_query = """ -query Q($after: String) { +query Q($after: String) { repository(name: "fastapi", owner: "tiangolo") { pullRequests(first: 100, after: $after) { edges { @@ -133,7 +133,7 @@ class Author(BaseModel): class CommentsNode(BaseModel): createdAt: datetime - author: Optional[Author] = None + author: Union[Author, None] = None class Comments(BaseModel): @@ -142,7 +142,7 @@ class Comments(BaseModel): class IssuesNode(BaseModel): number: int - author: Optional[Author] = None + author: Union[Author, None] = None title: str createdAt: datetime state: str @@ -179,7 +179,7 @@ class Labels(BaseModel): class ReviewNode(BaseModel): - author: Optional[Author] = None + author: Union[Author, None] = None state: str @@ -190,7 +190,7 @@ class Reviews(BaseModel): class PullRequestNode(BaseModel): number: int labels: Labels - author: Optional[Author] = None + author: Union[Author, None] = None title: str createdAt: datetime state: str @@ -260,19 +260,21 @@ class Settings(BaseSettings): input_token: SecretStr input_standard_token: SecretStr github_repository: str + httpx_timeout: int = 30 def get_graphql_response( - *, settings: Settings, query: str, after: Optional[str] = None + *, settings: Settings, query: str, after: Union[str, None] = None ): headers = {"Authorization": f"token {settings.input_token.get_secret_value()}"} variables = {"after": after} response = httpx.post( github_graphql_url, headers=headers, + timeout=settings.httpx_timeout, json={"query": query, "variables": variables, "operationName": "Q"}, ) - if not response.status_code == 200: + if response.status_code != 200: logging.error(f"Response was not 200, after: {after}") logging.error(response.text) raise RuntimeError(response.text) @@ -280,19 +282,19 @@ def get_graphql_response( return data -def get_graphql_issue_edges(*, settings: Settings, after: Optional[str] = None): +def get_graphql_issue_edges(*, settings: Settings, after: Union[str, None] = None): data = get_graphql_response(settings=settings, query=issues_query, after=after) graphql_response = IssuesResponse.parse_obj(data) return graphql_response.data.repository.issues.edges -def get_graphql_pr_edges(*, settings: Settings, after: Optional[str] = None): +def get_graphql_pr_edges(*, settings: Settings, after: Union[str, None] = None): data = get_graphql_response(settings=settings, query=prs_query, after=after) graphql_response = PRsResponse.parse_obj(data) return graphql_response.data.repository.pullRequests.edges -def get_graphql_sponsor_edges(*, settings: Settings, after: Optional[str] = None): +def get_graphql_sponsor_edges(*, settings: Settings, after: Union[str, None] = None): data = get_graphql_response(settings=settings, query=sponsors_query, after=after) graphql_response = SponsorsResponse.parse_obj(data) return graphql_response.data.user.sponsorshipsAsMaintainer.edges @@ -501,9 +503,16 @@ if __name__ == "__main__": github_sponsors_path = Path("./docs/en/data/github_sponsors.yml") people_old_content = people_path.read_text(encoding="utf-8") github_sponsors_old_content = github_sponsors_path.read_text(encoding="utf-8") - new_people_content = yaml.dump(people, sort_keys=False, width=200, allow_unicode=True) - new_github_sponsors_content = yaml.dump(github_sponsors, sort_keys=False, width=200, allow_unicode=True) - if people_old_content == new_people_content and github_sponsors_old_content == new_github_sponsors_content: + new_people_content = yaml.dump( + people, sort_keys=False, width=200, allow_unicode=True + ) + new_github_sponsors_content = yaml.dump( + github_sponsors, sort_keys=False, width=200, allow_unicode=True + ) + if ( + people_old_content == new_people_content + and github_sponsors_old_content == new_github_sponsors_content + ): logging.info("The FastAPI People data hasn't changed, finishing.") sys.exit(0) people_path.write_text(new_people_content, encoding="utf-8") @@ -517,7 +526,9 @@ if __name__ == "__main__": logging.info(f"Creating a new branch {branch_name}") subprocess.run(["git", "checkout", "-b", branch_name], check=True) logging.info("Adding updated file") - subprocess.run(["git", "add", str(people_path)], check=True) + subprocess.run( + ["git", "add", str(people_path), str(github_sponsors_path)], check=True + ) logging.info("Committing updated file") message = "👥 Update FastAPI People" result = subprocess.run(["git", "commit", "-m", message], check=True) diff --git a/.github/actions/watch-previews/app/main.py b/.github/actions/watch-previews/app/main.py index 3b3520599..51285d02b 100644 --- a/.github/actions/watch-previews/app/main.py +++ b/.github/actions/watch-previews/app/main.py @@ -1,7 +1,7 @@ import logging from datetime import datetime from pathlib import Path -from typing import List, Optional +from typing import List, Union import httpx from github import Github @@ -16,7 +16,7 @@ class Settings(BaseSettings): input_token: SecretStr github_repository: str github_event_path: Path - github_event_name: Optional[str] = None + github_event_name: Union[str, None] = None class Artifact(BaseModel): @@ -74,7 +74,7 @@ if __name__ == "__main__": logging.info(f"Docs preview was notified: {notified}") if not notified: artifact_name = f"docs-zip-{commit}" - use_artifact: Optional[Artifact] = None + use_artifact: Union[Artifact, None] = None for artifact in artifacts_response.artifacts: if artifact.name == artifact_name: use_artifact = artifact diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..cd972a0ba --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,16 @@ +version: 2 +updates: + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" + commit-message: + prefix: ⬆ + # Python + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "daily" + commit-message: + prefix: ⬆ diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index ccf964486..0d666b82a 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -1,6 +1,8 @@ name: Build Docs on: push: + branches: + - master pull_request: types: [opened, synchronize] jobs: @@ -11,16 +13,16 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: "3.7" - - uses: actions/cache@v2 + - uses: actions/cache@v3 id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-docs-v2 + key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-v03 - name: Install Flit if: steps.cache.outputs.cache-hit != 'true' run: python3.7 -m pip install flit @@ -28,18 +30,18 @@ jobs: if: steps.cache.outputs.cache-hit != 'true' run: python3.7 -m flit install --deps production --extras doc - name: Install Material for MkDocs Insiders - if: github.event.pull_request.head.repo.fork == false && steps.cache.outputs.cache-hit != 'true' + if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true' run: pip install git+https://${{ secrets.ACTIONS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git - name: Build Docs run: python3.7 ./scripts/docs.py build-all - name: Zip docs run: bash ./scripts/zip-docs.sh - - uses: actions/upload-artifact@v2 + - uses: actions/upload-artifact@v3 with: name: docs-zip path: ./docs.zip - name: Deploy to Netlify - uses: nwtgck/actions-netlify@v1.1.5 + uses: nwtgck/actions-netlify@v1.2.3 with: publish-dir: './site' production-branch: master diff --git a/.github/workflows/latest-changes.yml b/.github/workflows/latest-changes.yml index 42236beba..4aa8475b6 100644 --- a/.github/workflows/latest-changes.yml +++ b/.github/workflows/latest-changes.yml @@ -12,7 +12,7 @@ on: description: PR number required: true debug_enabled: - description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)' + description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)' required: false default: false @@ -20,7 +20,7 @@ jobs: latest-changes: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: # To allow latest-changes to commit to master token: ${{ secrets.ACTIONS_TOKEN }} diff --git a/.github/workflows/notify-translations.yml b/.github/workflows/notify-translations.yml index 7e414ab95..2fcb7595e 100644 --- a/.github/workflows/notify-translations.yml +++ b/.github/workflows/notify-translations.yml @@ -9,7 +9,7 @@ jobs: notify-translations: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 # Allow debugging with tmate - name: Setup tmate session uses: mxschmitt/action-tmate@v3 diff --git a/.github/workflows/people.yml b/.github/workflows/people.yml index 970813da7..4b47b4072 100644 --- a/.github/workflows/people.yml +++ b/.github/workflows/people.yml @@ -6,7 +6,7 @@ on: workflow_dispatch: inputs: debug_enabled: - description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)' + description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)' required: false default: false @@ -14,7 +14,7 @@ jobs: fastapi-people: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 # Allow debugging with tmate - name: Setup tmate session uses: mxschmitt/action-tmate@v3 diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml index 0c0d2ac59..d42b08543 100644 --- a/.github/workflows/preview-docs.yml +++ b/.github/workflows/preview-docs.yml @@ -3,16 +3,16 @@ on: workflow_run: workflows: - Build Docs - types: + types: - completed jobs: preview-docs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Download Artifact Docs - uses: dawidd6/action-download-artifact@v2.9.0 + uses: dawidd6/action-download-artifact@v2.23.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} workflow: build-docs.yml @@ -25,7 +25,7 @@ jobs: rm -f docs.zip - name: Deploy to Netlify id: netlify - uses: nwtgck/actions-netlify@v1.1.5 + uses: nwtgck/actions-netlify@v1.2.3 with: publish-dir: './site' production-deploy: false diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 9dde4e066..02846cefd 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -13,12 +13,12 @@ jobs: env: GITHUB_CONTEXT: ${{ toJson(github) }} run: echo "$GITHUB_CONTEXT" - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: "3.6" - - uses: actions/cache@v2 + - uses: actions/cache@v3 id: cache with: path: ${{ env.pythonLocation }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 21ea7c1a8..14dc141d9 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -16,16 +16,16 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - - uses: actions/cache@v2 + - uses: actions/cache@v3 id: cache with: path: ${{ env.pythonLocation }} - key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-test + key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-test-v02 - name: Install Flit if: steps.cache.outputs.cache-hit != 'true' run: pip install flit @@ -38,4 +38,4 @@ jobs: - name: Test run: bash scripts/test.sh - name: Upload coverage - uses: codecov/codecov-action@v1 + uses: codecov/codecov-action@v3 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..c4c1d4d9e --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,51 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.3.0 + hooks: + - id: check-added-large-files + - id: check-toml + - id: check-yaml + args: + - --unsafe + - id: end-of-file-fixer + - id: trailing-whitespace +- repo: https://github.com/asottile/pyupgrade + rev: v2.37.3 + hooks: + - id: pyupgrade + args: + - --py3-plus + - --keep-runtime-typing +- repo: https://github.com/myint/autoflake + rev: v1.5.3 + hooks: + - id: autoflake + args: + - --recursive + - --in-place + - --remove-all-unused-imports + - --remove-unused-variables + - --expand-star-imports + - --exclude + - __init__.py + - --remove-duplicate-keys +- repo: https://github.com/pycqa/isort + rev: 5.10.1 + hooks: + - id: isort + name: isort (python) + - id: isort + name: isort (cython) + types: [cython] + - id: isort + name: isort (pyi) + types: [pyi] +- repo: https://github.com/psf/black + rev: 22.8.0 + hooks: + - id: black +ci: + autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks + autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate diff --git a/README.md b/README.md index c9c69d3e8..bc00d9ed9 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,6 @@ FastAPI is a modern, fast (high-performance), web framework for building APIs wi The key features are: * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). - * **Fast to code**: Increase the speed to develop features by about 200% to 300%. * * **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * * **Intuitive**: Great editor support. Completion everywhere. Less time debugging. @@ -47,15 +46,17 @@ The key features are: - + + - + - - + + + @@ -130,7 +131,7 @@ $ pip install fastapi -You will also need an ASGI server, for production such as Uvicorn or Hypercorn. +You will also need an ASGI server, for production such as Uvicorn or Hypercorn.
@@ -149,7 +150,7 @@ $ pip install "uvicorn[standard]" * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,7 +163,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -172,7 +173,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,7 +186,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -264,7 +265,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 Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +276,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +285,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} diff --git a/SECURITY.md b/SECURITY.md index 322f95f62..db412cf2c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ Learn more about it below. 👇 ## Versions -The latest versions of FastAPI are supported. +The latest version of FastAPI is supported. You are encouraged to [write tests](https://fastapi.tiangolo.com/tutorial/testing/) for your application and update your FastAPI version frequently after ensuring that your tests are passing. This way you will benefit from the latest features, bug fixes, and **security fixes**. diff --git a/docs/az/mkdocs.yml b/docs/az/mkdocs.yml index 66220f63e..d549f37a3 100644 --- a/docs/az/mkdocs.yml +++ b/docs/az/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -69,6 +75,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +105,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +119,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +129,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/de/docs/features.md b/docs/de/docs/features.md index f56257e7e..f825472a9 100644 --- a/docs/de/docs/features.md +++ b/docs/de/docs/features.md @@ -13,7 +13,7 @@ ### Automatische Dokumentation -Mit einer interaktiven API-Dokumentation und explorativen webbasierten Benutzerschnittstellen. Da FastAPI auf OpenAPI basiert, gibt es hierzu mehrere Optionen, wobei zwei standartmäßig vorhanden sind. +Mit einer interaktiven API-Dokumentation und explorativen webbasierten Benutzerschnittstellen. Da FastAPI auf OpenAPI basiert, gibt es hierzu mehrere Optionen, wobei zwei standardmäßig vorhanden sind. * Swagger UI, bietet interaktive Exploration: testen und rufen Sie ihre API direkt vom Webbrowser auf. @@ -27,7 +27,7 @@ Mit einer interaktiven API-Dokumentation und explorativen webbasierten Benutzers Alles basiert auf **Python 3.6 Typ**-Deklarationen (dank Pydantic). Es muss keine neue Syntax gelernt werden, nur standardisiertes modernes Python. - + Wenn Sie eine kurze, zweiminütige, Auffrischung in der Benutzung von Python Typ-Deklarationen benötigen (auch wenn Sie FastAPI nicht nutzen), schauen Sie sich diese kurze Einführung an (Englisch): Python Types{.internal-link target=_blank}. @@ -97,9 +97,9 @@ Hierdurch werden Sie nie wieder einen falschen Schlüsselnamen benutzen und spar ### Kompakt -FastAPI nutzt für alles sensible **Standard-Einstellungen**, welche optional überall konfiguriert werden können. Alle Parameter können ganz genau an Ihre Bedürfnisse angepasst werden, sodass sie genau die API definieren können, die sie brachen. +FastAPI nutzt für alles sensible **Standard-Einstellungen**, welche optional überall konfiguriert werden können. Alle Parameter können ganz genau an Ihre Bedürfnisse angepasst werden, sodass sie genau die API definieren können, die sie brauchen. -Aber standartmäßig, **"funktioniert einfach"** alles. +Aber standardmäßig, **"funktioniert einfach"** alles. ### Validierung @@ -109,7 +109,7 @@ Aber standartmäßig, **"funktioniert einfach"** alles. * Zeichenketten (`str`), mit definierter minimaler und maximaler Länge. * Zahlen (`int`, `float`) mit minimaler und maximaler Größe, usw. -* Validierung für ungewögnliche Typen, wie: +* Validierung für ungewöhnliche Typen, wie: * URL. * Email. * UUID. @@ -119,9 +119,9 @@ Die gesamte Validierung übernimmt das etablierte und robuste **Pydantic**. ### Sicherheit und Authentifizierung -Sicherheit und Authentifizierung integriert. Ohne einen Kompromiss aufgrund einer Datenbank oder den Datenentitäten. +Integrierte Sicherheit und Authentifizierung. Ohne Kompromisse bei Datenbanken oder Datenmodellen. -Unterstützt alle von OpenAPI definierten Sicherheitsschemata, hierzu gehören: +Unterstützt werden alle von OpenAPI definierten Sicherheitsschemata, hierzu gehören: * HTTP Basis Authentifizierung. * **OAuth2** (auch mit **JWT Zugriffstokens**). Schauen Sie sich hierzu dieses Tutorial an: [OAuth2 mit JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. @@ -142,7 +142,7 @@ FastAPI enthält ein extrem einfaches, aber extrem mächtiges Starlette. Das bedeutet, auch ihr eigner Starlett Quellcode funktioniert. +**FastAPI** ist vollkommen kompatibel (und basiert auf) Starlette. Das bedeutet, auch ihr eigener Starlette Quellcode funktioniert. -`FastAPI` ist eigentlich eine Unterklasse von `Starlette`. Wenn sie also bereits Starlette kennen oder benutzen, können Sie das meiste Ihres Wissen direkt anwenden. +`FastAPI` ist eigentlich eine Unterklasse von `Starlette`. Wenn Sie also bereits Starlette kennen oder benutzen, können Sie das meiste Ihres Wissens direkt anwenden. Mit **FastAPI** bekommen Sie viele von **Starlette**'s Funktionen (da FastAPI nur Starlette auf Steroiden ist): -* Stark beeindruckende Performanz. Es ist eines der schnellsten Python frameworks, auf Augenhöhe mit **NodeJS** und **Go**. +* Stark beeindruckende Performanz. Es ist eines der schnellsten Python Frameworks, auf Augenhöhe mit **NodeJS** und **Go**. * **WebSocket**-Unterstützung. * Hintergrundaufgaben im selben Prozess. * Ereignisse für das Starten und Herunterfahren. @@ -193,11 +193,11 @@ Mit **FastAPI** bekommen Sie alle Funktionen von **Pydantic** (da FastAPI für d * Gutes Zusammenspiel mit Ihrer/Ihrem **IDE/linter/Gehirn**: * Weil Datenstrukturen von Pydantic einfach nur Instanzen ihrer definierten Klassen sind, sollten Autovervollständigung, Linting, mypy und ihre Intuition einwandfrei funktionieren. * **Schnell**: - * In Vergleichen ist Pydantic schneller als jede andere getestete Bibliothek. + * In Vergleichen ist Pydantic schneller als jede andere getestete Bibliothek. * Validierung von **komplexen Strukturen**: * Benutzung von hierachischen Pydantic Schemata, Python `typing`’s `List` und `Dict`, etc. - * Validierungen erlauben klare und einfache Datenschemadefinition, überprüft und dokumentiert als JSON Schema. + * Validierungen erlauben eine klare und einfache Datenschemadefinition, überprüft und dokumentiert als JSON Schema. * Sie können stark **verschachtelte JSON** Objekte haben und diese sind trotzdem validiert und annotiert. * **Erweiterbar**: - * Pydantic erlaubt die Definition von eigenen Datentypen oder sie können die Validierung mit einer `validator` dekorierten Methode erweitern.. + * Pydantic erlaubt die Definition von eigenen Datentypen oder sie können die Validierung mit einer `validator` dekorierten Methode erweitern. * 100% Testabdeckung. diff --git a/docs/de/docs/index.md b/docs/de/docs/index.md index d09ce70a0..287c79cff 100644 --- a/docs/de/docs/index.md +++ b/docs/de/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -149,7 +149,7 @@ $ pip install uvicorn[standard] * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,7 +162,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,7 +185,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -264,7 +264,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 Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +275,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +284,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. diff --git a/docs/de/mkdocs.yml b/docs/de/mkdocs.yml index 360fa8c4a..8c3c42b5f 100644 --- a/docs/de/mkdocs.yml +++ b/docs/de/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -70,6 +76,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -98,8 +106,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -108,6 +120,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -116,6 +130,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/en/data/external_links.yml b/docs/en/data/external_links.yml index 0850d9788..e9c4ef2f2 100644 --- a/docs/en/data/external_links.yml +++ b/docs/en/data/external_links.yml @@ -1,5 +1,21 @@ articles: english: + - author: New Relic + author_link: https://newrelic.com + link: https://newrelic.com/instant-observability/fastapi/e559ec64-f765-4470-a15f-1901fcebb468 + title: How to monitor FastAPI application performance using Python agent + - author: Jean-Baptiste Rocher + author_link: https://hashnode.com/@jibrocher + link: https://dev.indooroutdoor.io/series/fastapi-react-poll-app + title: Building the Poll App From Django Tutorial With FastAPI And React + - author: Silvan Melchior + author_link: https://github.com/silvanmelchior + link: https://blog.devgenius.io/seamless-fastapi-configuration-with-confz-90949c14ea12 + title: Seamless FastAPI Configuration with ConfZ + - author: Kaustubh Gupta + author_link: https://medium.com/@kaustubhgupta1828/ + link: https://levelup.gitconnected.com/5-advance-features-of-fastapi-you-should-try-7c0ac7eebb3e + title: 5 Advanced Features of FastAPI You Should Try - author: Kaustubh Gupta author_link: https://medium.com/@kaustubhgupta1828/ link: https://www.analyticsvidhya.com/blog/2021/06/deploying-ml-models-as-api-using-fastapi-and-heroku/ @@ -12,6 +28,10 @@ articles: author_link: https://pystar.substack.com/ link: https://pystar.substack.com/p/how-to-create-a-fake-certificate title: How to Create A Fake Certificate Authority And Generate TLS Certs for FastAPI + - author: Ben Gamble + author_link: https://uk.linkedin.com/in/bengamble7 + link: https://ably.com/blog/realtime-ticket-booking-solution-kafka-fastapi-ably + title: Building a realtime ticket booking solution with Kafka, FastAPI, and Ably - author: Shahriyar(Shako) Rzayev author_link: https://www.linkedin.com/in/shahriyar-rzayev/ link: https://www.azepug.az/posts/fastapi/#building-simple-e-commerce-with-nuxtjs-and-fastapi-series @@ -20,6 +40,10 @@ articles: author_link: https://rodrigo-arenas.medium.com/ link: https://medium.com/analytics-vidhya/serve-a-machine-learning-model-using-sklearn-fastapi-and-docker-85aabf96729b title: "Serve a machine learning model using Sklearn, FastAPI and Docker" + - author: Yashasvi Singh + author_link: https://hashnode.com/@aUnicornDev + link: https://aunicorndev.hashnode.dev/series/supafast-api + title: "Building an API with FastAPI and Supabase and Deploying on Deta" - author: Navule Pavan Kumar Rao author_link: https://www.linkedin.com/in/navule/ link: https://www.tutlinks.com/deploy-fastapi-on-ubuntu-gunicorn-caddy-2/ @@ -27,7 +51,7 @@ articles: - author: Patrick Ladon author_link: https://dev.to/factorlive link: https://dev.to/factorlive/python-facebook-messenger-webhook-with-fastapi-on-glitch-4n90 - title: Python Facebook messenger webhook with FastAPI on Glitch + title: Python Facebook messenger webhook with FastAPI on Glitch - author: Dom Patmore author_link: https://twitter.com/dompatmore link: https://dompatmore.com/blog/authenticate-your-fastapi-app-with-auth0 @@ -188,11 +212,23 @@ articles: author_link: https://medium.com/@williamhayes link: https://medium.com/@williamhayes/fastapi-starlette-debug-vs-prod-5f7561db3a59 title: FastAPI/Starlette debug vs prod + - author: Mukul Mantosh + author_link: https://twitter.com/MantoshMukul + link: https://www.jetbrains.com/pycharm/guide/tutorials/fastapi-aws-kubernetes/ + title: Developing FastAPI Application using K8s & AWS + - author: KrishNa + author_link: https://medium.com/@krishnardt365 + link: https://medium.com/@krishnardt365/fastapi-docker-and-postgres-91943e71be92 + title: Fastapi, Docker(Docker compose) and Postgres german: - author: Nico Axtmann author_link: https://twitter.com/_nicoax link: https://blog.codecentric.de/2019/08/inbetriebnahme-eines-scikit-learn-modells-mit-onnx-und-fastapi/ title: Inbetriebnahme eines scikit-learn-Modells mit ONNX und FastAPI + - author: Felix Schürmeyer + author_link: https://hellocoding.de/autor/felix-schuermeyer/ + link: https://hellocoding.de/blog/coding-language/python/fastapi + title: REST-API Programmieren mittels Python und dem FastAPI Modul japanese: - author: '@bee2' author_link: https://qiita.com/bee2 diff --git a/docs/en/data/github_sponsors.yml b/docs/en/data/github_sponsors.yml index 162a8dbe2..891a990a4 100644 --- a/docs/en/data/github_sponsors.yml +++ b/docs/en/data/github_sponsors.yml @@ -2,87 +2,159 @@ sponsors: - - login: jina-ai avatarUrl: https://avatars.githubusercontent.com/u/60539444?v=4 url: https://github.com/jina-ai +- - login: Doist + avatarUrl: https://avatars.githubusercontent.com/u/2565372?v=4 + url: https://github.com/Doist + - login: cryptapi + avatarUrl: https://avatars.githubusercontent.com/u/44925437?u=61369138589bc7fee6c417f3fbd50fbd38286cc4&v=4 + url: https://github.com/cryptapi +- - login: ObliviousAI + avatarUrl: https://avatars.githubusercontent.com/u/65656077?v=4 + url: https://github.com/ObliviousAI + - login: Lovage-Labs + avatarUrl: https://avatars.githubusercontent.com/u/71685552?v=4 + url: https://github.com/Lovage-Labs + - login: chaserowbotham + avatarUrl: https://avatars.githubusercontent.com/u/97751084?v=4 + url: https://github.com/chaserowbotham - - login: mikeckennedy - avatarUrl: https://avatars.githubusercontent.com/u/2035561?v=4 + avatarUrl: https://avatars.githubusercontent.com/u/2035561?u=1bb18268bcd4d9249e1f783a063c27df9a84c05b&v=4 url: https://github.com/mikeckennedy - - login: RodneyU215 - avatarUrl: https://avatars.githubusercontent.com/u/3329665?u=ec6a9adf8e7e8e306eed7d49687c398608d1604f&v=4 - url: https://github.com/RodneyU215 - login: Trivie avatarUrl: https://avatars.githubusercontent.com/u/8161763?v=4 url: https://github.com/Trivie - login: deta avatarUrl: https://avatars.githubusercontent.com/u/47275976?v=4 url: https://github.com/deta + - login: deepset-ai + avatarUrl: https://avatars.githubusercontent.com/u/51827949?v=4 + url: https://github.com/deepset-ai - login: investsuite avatarUrl: https://avatars.githubusercontent.com/u/73833632?v=4 url: https://github.com/investsuite - - login: vimsoHQ - avatarUrl: https://avatars.githubusercontent.com/u/77627231?v=4 - url: https://github.com/vimsoHQ -- - login: newrelic - avatarUrl: https://avatars.githubusercontent.com/u/31739?v=4 - url: https://github.com/newrelic - - login: qaas - avatarUrl: https://avatars.githubusercontent.com/u/8503759?u=10a6b4391ad6ab4cf9487ce54e3fcb61322d1efc&v=4 - url: https://github.com/qaas + - login: VincentParedes + avatarUrl: https://avatars.githubusercontent.com/u/103889729?v=4 + url: https://github.com/VincentParedes +- - login: InesIvanova + avatarUrl: https://avatars.githubusercontent.com/u/22920417?u=409882ec1df6dbd77455788bb383a8de223dbf6f&v=4 + url: https://github.com/InesIvanova +- - login: SendCloud + avatarUrl: https://avatars.githubusercontent.com/u/7831959?v=4 + url: https://github.com/SendCloud + - login: mercedes-benz + avatarUrl: https://avatars.githubusercontent.com/u/34240465?v=4 + url: https://github.com/mercedes-benz + - login: xoflare + avatarUrl: https://avatars.githubusercontent.com/u/74335107?v=4 + url: https://github.com/xoflare + - login: Striveworks + avatarUrl: https://avatars.githubusercontent.com/u/45523576?v=4 + url: https://github.com/Striveworks + - login: BoostryJP + avatarUrl: https://avatars.githubusercontent.com/u/57932412?v=4 + url: https://github.com/BoostryJP + - login: Jonathanjwp + avatarUrl: https://avatars.githubusercontent.com/u/110426978?u=5e6ed4984022cb8886c4fdfdc0c59f55c48a2f1d&v=4 + url: https://github.com/Jonathanjwp - - login: johnadjei avatarUrl: https://avatars.githubusercontent.com/u/767860?v=4 url: https://github.com/johnadjei + - login: HiredScore + avatarUrl: https://avatars.githubusercontent.com/u/3908850?v=4 + url: https://github.com/HiredScore - login: wdwinslow avatarUrl: https://avatars.githubusercontent.com/u/11562137?u=dc01daafb354135603a263729e3d26d939c0c452&v=4 url: https://github.com/wdwinslow -- - login: kamalgill - avatarUrl: https://avatars.githubusercontent.com/u/133923?u=0df9181d97436ce330e9acf90ab8a54b7022efe7&v=4 - url: https://github.com/kamalgill - - login: grillazz - avatarUrl: https://avatars.githubusercontent.com/u/3415861?u=16d7d0ffa5dfb99f8834f8f76d90e138ba09b94a&v=4 - url: https://github.com/grillazz + - login: khalidelboray + avatarUrl: https://avatars.githubusercontent.com/u/37024839?u=9a4b19123b5a1ba39dc581f8e4e1bc53fafdda2e&v=4 + url: https://github.com/khalidelboray +- - login: moellenbeck + avatarUrl: https://avatars.githubusercontent.com/u/169372?v=4 + url: https://github.com/moellenbeck + - login: RodneyU215 + avatarUrl: https://avatars.githubusercontent.com/u/3329665?u=ec6a9adf8e7e8e306eed7d49687c398608d1604f&v=4 + url: https://github.com/RodneyU215 - login: tizz98 avatarUrl: https://avatars.githubusercontent.com/u/5739698?u=f095a3659e3a8e7c69ccd822696990b521ea25f9&v=4 url: https://github.com/tizz98 + - login: Vikka + avatarUrl: https://avatars.githubusercontent.com/u/9381120?u=4bfc7032a824d1ed1994aa8256dfa597c8f187ad&v=4 + url: https://github.com/Vikka - login: jmaralc avatarUrl: https://avatars.githubusercontent.com/u/21101214?u=b15a9f07b7cbf6c9dcdbcb6550bbd2c52f55aa50&v=4 url: https://github.com/jmaralc - - login: AlexandruSimion - avatarUrl: https://avatars.githubusercontent.com/u/71321732?v=4 - url: https://github.com/AlexandruSimion -- - login: samuelcolvin + - login: takashi-yoneya + avatarUrl: https://avatars.githubusercontent.com/u/33813153?u=2d0522bceba0b8b69adf1f2db866503bd96f944e&v=4 + url: https://github.com/takashi-yoneya + - login: leynier + avatarUrl: https://avatars.githubusercontent.com/u/36774373?u=2284831c821307de562ebde5b59014d5416c7e0d&v=4 + url: https://github.com/leynier + - login: mainframeindustries + avatarUrl: https://avatars.githubusercontent.com/u/55092103?v=4 + url: https://github.com/mainframeindustries + - login: DelfinaCare + avatarUrl: https://avatars.githubusercontent.com/u/83734439?v=4 + url: https://github.com/DelfinaCare +- - login: povilasb + avatarUrl: https://avatars.githubusercontent.com/u/1213442?u=b11f58ed6ceea6e8297c9b310030478ebdac894d&v=4 + url: https://github.com/povilasb + - login: primer-io + avatarUrl: https://avatars.githubusercontent.com/u/62146168?v=4 + url: https://github.com/primer-io +- - login: ekpyrosis + avatarUrl: https://avatars.githubusercontent.com/u/60075?v=4 + url: https://github.com/ekpyrosis + - login: ryangrose + avatarUrl: https://avatars.githubusercontent.com/u/24993976?u=052f346aa859f3e52c21bd2c1792f61a98cfbacf&v=4 + url: https://github.com/ryangrose + - login: A-Edge + avatarUrl: https://avatars.githubusercontent.com/u/59514131?v=4 + url: https://github.com/A-Edge +- - login: Kludex + avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4 + url: https://github.com/Kludex + - login: samuelcolvin avatarUrl: https://avatars.githubusercontent.com/u/4039449?u=807390ba9cfe23906c3bf8a0d56aaca3cf2bfa0d&v=4 url: https://github.com/samuelcolvin - - login: jokull - avatarUrl: https://avatars.githubusercontent.com/u/701?u=0532b62166893d5160ef795c4c8b7512d971af05&v=4 - url: https://github.com/jokull + - login: jefftriplett + avatarUrl: https://avatars.githubusercontent.com/u/50527?u=af1ddfd50f6afd6d99f333ba2ac8d0a5b245ea74&v=4 + url: https://github.com/jefftriplett + - login: medecau + avatarUrl: https://avatars.githubusercontent.com/u/59870?u=f9341c95adaba780828162fd4c7442357ecfcefa&v=4 + url: https://github.com/medecau + - login: kamalgill + avatarUrl: https://avatars.githubusercontent.com/u/133923?u=0df9181d97436ce330e9acf90ab8a54b7022efe7&v=4 + url: https://github.com/kamalgill + - login: dekoza + avatarUrl: https://avatars.githubusercontent.com/u/210980?u=c03c78a8ae1039b500dfe343665536ebc51979b2&v=4 + url: https://github.com/dekoza + - login: deserat + avatarUrl: https://avatars.githubusercontent.com/u/299332?v=4 + url: https://github.com/deserat + - login: ericof + avatarUrl: https://avatars.githubusercontent.com/u/306014?u=cf7c8733620397e6584a451505581c01c5d842d7&v=4 + url: https://github.com/ericof - login: wshayes avatarUrl: https://avatars.githubusercontent.com/u/365303?u=07ca03c5ee811eb0920e633cc3c3db73dbec1aa5&v=4 url: https://github.com/wshayes - login: koxudaxi avatarUrl: https://avatars.githubusercontent.com/u/630670?u=507d8577b4b3670546b449c4c2ccbc5af40d72f7&v=4 url: https://github.com/koxudaxi - - login: falkben - avatarUrl: https://avatars.githubusercontent.com/u/653031?u=0c8d8f33d87f1aa1a6488d3f02105e9abc838105&v=4 - url: https://github.com/falkben - login: jqueguiner - avatarUrl: https://avatars.githubusercontent.com/u/690878?u=e4835b2a985a0f2d52018e4926cb5a58c26a62e8&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/690878?u=bd65cc1f228ce6455e56dfaca3ef47c33bc7c3b0&v=4 url: https://github.com/jqueguiner - - login: Mazyod - avatarUrl: https://avatars.githubusercontent.com/u/860511?v=4 - url: https://github.com/Mazyod + - login: alexsantos + avatarUrl: https://avatars.githubusercontent.com/u/932219?v=4 + url: https://github.com/alexsantos + - login: tcsmith + avatarUrl: https://avatars.githubusercontent.com/u/989034?u=7d8d741552b3279e8f4d3878679823a705a46f8f&v=4 + url: https://github.com/tcsmith - login: ltieman avatarUrl: https://avatars.githubusercontent.com/u/1084689?u=e69b17de17cb3ca141a17daa7ccbe173ceb1eb17&v=4 url: https://github.com/ltieman - - login: mrmattwright - avatarUrl: https://avatars.githubusercontent.com/u/1277725?v=4 - url: https://github.com/mrmattwright - - login: westonsteimel - avatarUrl: https://avatars.githubusercontent.com/u/1593939?u=0f2c0e3647f916fe295d62fa70da7a4c177115e3&v=4 - url: https://github.com/westonsteimel - - login: timdrijvers - avatarUrl: https://avatars.githubusercontent.com/u/1694939?v=4 - url: https://github.com/timdrijvers - - login: mrgnw - avatarUrl: https://avatars.githubusercontent.com/u/2504532?u=7ec43837a6d0afa80f96f0788744ea6341b89f97&v=4 - url: https://github.com/mrgnw + - login: corleyma + avatarUrl: https://avatars.githubusercontent.com/u/2080732?u=aed2ff652294a87d666b1c3f6dbe98104db76d26&v=4 + url: https://github.com/corleyma - login: madisonmay avatarUrl: https://avatars.githubusercontent.com/u/2645393?u=f22b93c6ea345a4d26a90a3834dfc7f0789fcb63&v=4 url: https://github.com/madisonmay @@ -93,149 +165,206 @@ sponsors: avatarUrl: https://avatars.githubusercontent.com/u/3148093?v=4 url: https://github.com/andre1sk - login: Shark009 - avatarUrl: https://avatars.githubusercontent.com/u/3163309?v=4 + avatarUrl: https://avatars.githubusercontent.com/u/3163309?u=0c6f4091b0eda05c44c390466199826e6dc6e431&v=4 url: https://github.com/Shark009 + - login: grillazz + avatarUrl: https://avatars.githubusercontent.com/u/3415861?u=0b32b7073ae1ab8b7f6d2db0188c2e1e357ff451&v=4 + url: https://github.com/grillazz + - login: dblackrun + avatarUrl: https://avatars.githubusercontent.com/u/3528486?v=4 + url: https://github.com/dblackrun + - login: zsinx6 + avatarUrl: https://avatars.githubusercontent.com/u/3532625?u=ba75a5dc744d1116ccfeaaf30d41cb2fe81fe8dd&v=4 + url: https://github.com/zsinx6 + - login: aacayaco + avatarUrl: https://avatars.githubusercontent.com/u/3634801?u=eaadda178c964178fcb64886f6c732172c8f8219&v=4 + url: https://github.com/aacayaco + - login: anomaly + avatarUrl: https://avatars.githubusercontent.com/u/3654837?v=4 + url: https://github.com/anomaly - login: peterHoburg avatarUrl: https://avatars.githubusercontent.com/u/3860655?u=f55f47eb2d6a9b495e806ac5a044e3ae01ccc1fa&v=4 url: https://github.com/peterHoburg + - login: jgreys + avatarUrl: https://avatars.githubusercontent.com/u/4136890?u=b579fd97033269a5e703ab509c7d5478b146cc2d&v=4 + url: https://github.com/jgreys + - login: gorhack + avatarUrl: https://avatars.githubusercontent.com/u/4141690?u=ec119ebc4bdf00a7bc84657a71aa17834f4f27f3&v=4 + url: https://github.com/gorhack - login: jaredtrog avatarUrl: https://avatars.githubusercontent.com/u/4381365?v=4 url: https://github.com/jaredtrog + - login: oliverxchen + avatarUrl: https://avatars.githubusercontent.com/u/4471774?u=534191f25e32eeaadda22dfab4b0a428733d5489&v=4 + url: https://github.com/oliverxchen - login: CINOAdam - avatarUrl: https://avatars.githubusercontent.com/u/4728508?u=34c3d58cb900fed475d0172b436c66a94ad739ed&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/4728508?u=76ef23f06ae7c604e009873bc27cf0ea9ba738c9&v=4 url: https://github.com/CINOAdam - - login: dudil - avatarUrl: https://avatars.githubusercontent.com/u/4785835?u=58b7ea39123e0507f3b2996448a27256b16fd697&v=4 - url: https://github.com/dudil + - login: ScrimForever + avatarUrl: https://avatars.githubusercontent.com/u/5040124?u=091ec38bfe16d6e762099e91309b59f248616a65&v=4 + url: https://github.com/ScrimForever - login: ennui93 avatarUrl: https://avatars.githubusercontent.com/u/5300907?u=5b5452725ddb391b2caaebf34e05aba873591c3a&v=4 url: https://github.com/ennui93 - - login: MacroPower - avatarUrl: https://avatars.githubusercontent.com/u/5648814?u=e13991efd1e03c44c911f919872e750530ded633&v=4 - url: https://github.com/MacroPower - - login: ginomempin - avatarUrl: https://avatars.githubusercontent.com/u/6091865?v=4 - url: https://github.com/ginomempin + - login: Yaleesa + avatarUrl: https://avatars.githubusercontent.com/u/6135475?v=4 + url: https://github.com/Yaleesa - login: iwpnd avatarUrl: https://avatars.githubusercontent.com/u/6152183?u=b2286006daafff5f991557344fee20b5da59639a&v=4 url: https://github.com/iwpnd + - login: simw + avatarUrl: https://avatars.githubusercontent.com/u/6322526?v=4 + url: https://github.com/simw + - login: pkucmus + avatarUrl: https://avatars.githubusercontent.com/u/6347418?u=98f5918b32e214a168a2f5d59b0b8ebdf57dca0d&v=4 + url: https://github.com/pkucmus - login: s3ich4n avatarUrl: https://avatars.githubusercontent.com/u/6926298?u=ba3025d698e1c986655e776ae383a3d60d9d578e&v=4 url: https://github.com/s3ich4n - login: Rehket avatarUrl: https://avatars.githubusercontent.com/u/7015688?u=3afb0ba200feebbc7f958950e92db34df2a3c172&v=4 url: https://github.com/Rehket - - login: christippett - avatarUrl: https://avatars.githubusercontent.com/u/7218120?u=434b9d29287d7de25772d94ddc74a9bd6d969284&v=4 - url: https://github.com/christippett - - login: Kludex - avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=cf8455cb899806b774a3a71073f88583adec99f6&v=4 - url: https://github.com/Kludex + - login: hiancdtrsnm + avatarUrl: https://avatars.githubusercontent.com/u/7343177?v=4 + url: https://github.com/hiancdtrsnm - login: Shackelford-Arden avatarUrl: https://avatars.githubusercontent.com/u/7362263?v=4 url: https://github.com/Shackelford-Arden - - login: cristeaadrian - avatarUrl: https://avatars.githubusercontent.com/u/9112724?v=4 - url: https://github.com/cristeaadrian - - login: otivvormes - avatarUrl: https://avatars.githubusercontent.com/u/11317418?u=6de1edefb6afd0108c0ad2816bd6efc4464a9c44&v=4 - url: https://github.com/otivvormes - - login: iambobmae - avatarUrl: https://avatars.githubusercontent.com/u/12390270?u=c9a35c2ee5092a9b4135ebb1f91b7f521c467031&v=4 - url: https://github.com/iambobmae - - login: ronaldnwilliams - avatarUrl: https://avatars.githubusercontent.com/u/13632749?u=ac41a086d0728bf66a9d2bee9e5e377041ff44a4&v=4 - url: https://github.com/ronaldnwilliams + - login: Ge0f3 + avatarUrl: https://avatars.githubusercontent.com/u/11887760?u=ccd80f1ac36dcb8517ef5c4e702e8cc5a80cad2f&v=4 + url: https://github.com/Ge0f3 + - login: svats2k + avatarUrl: https://avatars.githubusercontent.com/u/12378398?u=ecf28c19f61052e664bdfeb2391f8107d137915c&v=4 + url: https://github.com/svats2k + - login: gokulyc + avatarUrl: https://avatars.githubusercontent.com/u/13468848?u=269f269d3e70407b5fb80138c52daba7af783997&v=4 + url: https://github.com/gokulyc + - login: dannywade + avatarUrl: https://avatars.githubusercontent.com/u/13680237?u=418ee985bd41577b20fde81417fb2d901e875e8a&v=4 + url: https://github.com/dannywade - login: pablonnaoji avatarUrl: https://avatars.githubusercontent.com/u/15187159?u=afc15bd5a4ba9c5c7206bbb1bcaeef606a0932e0&v=4 url: https://github.com/pablonnaoji - - login: natenka - avatarUrl: https://avatars.githubusercontent.com/u/15850513?u=00d1083c980d0b4ce32835dc07eee7f43f34fd2f&v=4 - url: https://github.com/natenka - - login: la-mar - avatarUrl: https://avatars.githubusercontent.com/u/16618300?u=7755c0521d2bb0d704f35a51464b15c1e2e6c4da&v=4 - url: https://github.com/la-mar - login: robintully avatarUrl: https://avatars.githubusercontent.com/u/17059673?u=862b9bb01513f5acd30df97433cb97a24dbfb772&v=4 url: https://github.com/robintully - - login: ShaulAb - avatarUrl: https://avatars.githubusercontent.com/u/18129076?u=2c8d48e47f2dbee15c3f89c3d17d4c356504386c&v=4 - url: https://github.com/ShaulAb - login: wedwardbeck avatarUrl: https://avatars.githubusercontent.com/u/19333237?u=1de4ae2bf8d59eb4c013f21d863cbe0f2010575f&v=4 url: https://github.com/wedwardbeck - - login: linusg - avatarUrl: https://avatars.githubusercontent.com/u/19366641?u=125e390abef8fff3b3b0d370c369cba5d7fd4c67&v=4 - url: https://github.com/linusg - login: RedCarpetUp avatarUrl: https://avatars.githubusercontent.com/u/20360440?v=4 url: https://github.com/RedCarpetUp - login: Filimoa avatarUrl: https://avatars.githubusercontent.com/u/21352040?u=75e02d102d2ee3e3d793e555fa5c63045913ccb0&v=4 url: https://github.com/Filimoa - - login: raminsj13 - avatarUrl: https://avatars.githubusercontent.com/u/24259406?u=d51f2a526312ebba150a06936ed187ca0727d329&v=4 - url: https://github.com/raminsj13 - - login: comoelcometa - avatarUrl: https://avatars.githubusercontent.com/u/25950317?u=c6751efa038561b9bc5fa56d1033d5174e10cd65&v=4 - url: https://github.com/comoelcometa + - login: shuheng-liu + avatarUrl: https://avatars.githubusercontent.com/u/22414322?u=813c45f30786c6b511b21a661def025d8f7b609e&v=4 + url: https://github.com/shuheng-liu + - login: Joeriksson + avatarUrl: https://avatars.githubusercontent.com/u/25037079?v=4 + url: https://github.com/Joeriksson + - login: cometa-haley + avatarUrl: https://avatars.githubusercontent.com/u/25950317?u=cec1a3e0643b785288ae8260cc295a85ab344995&v=4 + url: https://github.com/cometa-haley + - login: LarryGF + avatarUrl: https://avatars.githubusercontent.com/u/26148349?u=431bb34d36d41c172466252242175281ae132152&v=4 + url: https://github.com/LarryGF - login: veprimk avatarUrl: https://avatars.githubusercontent.com/u/29689749?u=f8cb5a15a286e522e5b189bc572d5a1a90217fb2&v=4 url: https://github.com/veprimk - - login: orihomie - avatarUrl: https://avatars.githubusercontent.com/u/29889683?u=6bc2135a52fcb3a49e69e7d50190796618185fda&v=4 - url: https://github.com/orihomie - - login: SaltyCoco - avatarUrl: https://avatars.githubusercontent.com/u/31451104?u=6ee4e17c07d21b7054f54a12fa9cc377a1b24ff9&v=4 - url: https://github.com/SaltyCoco + - login: BrettskiPy + avatarUrl: https://avatars.githubusercontent.com/u/30988215?u=d8a94a67e140d5ee5427724b292cc52d8827087a&v=4 + url: https://github.com/BrettskiPy - login: mauroalejandrojm avatarUrl: https://avatars.githubusercontent.com/u/31569442?u=cdada990a1527926a36e95f62c30a8b48bbc49a1&v=4 url: https://github.com/mauroalejandrojm - - login: bulkw4r3 - avatarUrl: https://avatars.githubusercontent.com/u/35562532?u=0b812a14a02de14bf73d05fb2b2760a67bacffc2&v=4 - url: https://github.com/bulkw4r3 + - login: Leay15 + avatarUrl: https://avatars.githubusercontent.com/u/32212558?u=c4aa9c1737e515959382a5515381757b1fd86c53&v=4 + url: https://github.com/Leay15 + - login: AlrasheedA + avatarUrl: https://avatars.githubusercontent.com/u/33544979?u=7fe66bf62b47682612b222e3e8f4795ef3be769b&v=4 + url: https://github.com/AlrasheedA + - login: ProteinQure + avatarUrl: https://avatars.githubusercontent.com/u/33707203?v=4 + url: https://github.com/ProteinQure - login: ybressler - avatarUrl: https://avatars.githubusercontent.com/u/40807730?u=6621dc9ab53b697912ab2a32211bb29ae90a9112&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/40807730?u=41e2c00f1eebe3c402635f0325e41b4e6511462c&v=4 url: https://github.com/ybressler - - login: dbanty - avatarUrl: https://avatars.githubusercontent.com/u/43723790?u=0cf33e4f40efc2ea206a1189fd63a11344eb88ed&v=4 - url: https://github.com/dbanty + - login: ddilidili + avatarUrl: https://avatars.githubusercontent.com/u/42176885?u=c0a849dde06987434653197b5f638d3deb55fc6c&v=4 + url: https://github.com/ddilidili + - login: VictorCalderon + avatarUrl: https://avatars.githubusercontent.com/u/44529243?u=cea69884f826a29aff1415493405209e0706d07a&v=4 + url: https://github.com/VictorCalderon + - login: arthuRHD + avatarUrl: https://avatars.githubusercontent.com/u/48015496?u=05a0d5b8b9320eeb7990d35c9337b823f269d2ff&v=4 + url: https://github.com/arthuRHD + - login: rafsaf + avatarUrl: https://avatars.githubusercontent.com/u/51059348?u=f8f0d6d6e90fac39fa786228158ba7f013c74271&v=4 + url: https://github.com/rafsaf + - login: yezz123 + avatarUrl: https://avatars.githubusercontent.com/u/52716203?u=636b4f79645176df4527dd45c12d5dbb5a4193cf&v=4 + url: https://github.com/yezz123 - login: dudikbender avatarUrl: https://avatars.githubusercontent.com/u/53487583?u=494f85229115076121b3639a3806bbac1c6ae7f6&v=4 url: https://github.com/dudikbender - - login: primer-io - avatarUrl: https://avatars.githubusercontent.com/u/62146168?v=4 - url: https://github.com/primer-io - - login: tkrestiankova - avatarUrl: https://avatars.githubusercontent.com/u/67013045?v=4 - url: https://github.com/tkrestiankova + - login: dazeddd + avatarUrl: https://avatars.githubusercontent.com/u/59472056?u=7a1b668449bf8b448db13e4c575576d24d7d658b&v=4 + url: https://github.com/dazeddd + - login: yakkonaut + avatarUrl: https://avatars.githubusercontent.com/u/60633704?u=90a71fd631aa998ba4a96480788f017c9904e07b&v=4 + url: https://github.com/yakkonaut + - login: patsatsia + avatarUrl: https://avatars.githubusercontent.com/u/61111267?u=419516384f798a35e9d9e2dd81282cc46c151b58&v=4 + url: https://github.com/patsatsia + - login: predictionmachine + avatarUrl: https://avatars.githubusercontent.com/u/63719559?v=4 + url: https://github.com/predictionmachine + - login: minsau + avatarUrl: https://avatars.githubusercontent.com/u/64386242?u=7e45f24b2958caf946fa3546ea33bacf5cd886f8&v=4 + url: https://github.com/minsau - login: daverin avatarUrl: https://avatars.githubusercontent.com/u/70378377?u=6d1814195c0de7162820eaad95a25b423a3869c0&v=4 url: https://github.com/daverin - login: anthonycepeda - avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=892f700c79f9732211bd5221bf16eec32356a732&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/72019805?u=4252c6b6dc5024af502a823a3ac5e7a03a69963f&v=4 url: https://github.com/anthonycepeda - - login: an-tho-ny - avatarUrl: https://avatars.githubusercontent.com/u/74874159?v=4 - url: https://github.com/an-tho-ny + - login: dotlas + avatarUrl: https://avatars.githubusercontent.com/u/88832003?v=4 + url: https://github.com/dotlas + - login: pyt3h + avatarUrl: https://avatars.githubusercontent.com/u/99658549?v=4 + url: https://github.com/pyt3h +- - login: raestrada95 + avatarUrl: https://avatars.githubusercontent.com/u/34411704?u=f32b7e8f57a3f7e2a99e2bc115356f89f094f340&v=4 + url: https://github.com/raestrada95 - - login: linux-china avatarUrl: https://avatars.githubusercontent.com/u/46711?v=4 url: https://github.com/linux-china + - login: ddanier + avatarUrl: https://avatars.githubusercontent.com/u/113563?u=ed1dc79de72f93bd78581f88ebc6952b62f472da&v=4 + url: https://github.com/ddanier - login: jhb avatarUrl: https://avatars.githubusercontent.com/u/142217?v=4 url: https://github.com/jhb + - login: justinrmiller + avatarUrl: https://avatars.githubusercontent.com/u/143998?u=b507a940394d4fc2bc1c27cea2ca9c22538874bd&v=4 + url: https://github.com/justinrmiller + - login: bryanculbertson + avatarUrl: https://avatars.githubusercontent.com/u/144028?u=defda4f90e93429221cc667500944abde60ebe4a&v=4 + url: https://github.com/bryanculbertson + - login: hhatto + avatarUrl: https://avatars.githubusercontent.com/u/150309?u=3e8f63c27bf996bfc68464b0ce3f7a3e40e6ea7f&v=4 + url: https://github.com/hhatto - login: yourkin - avatarUrl: https://avatars.githubusercontent.com/u/178984?v=4 + avatarUrl: https://avatars.githubusercontent.com/u/178984?u=fa7c3503b47bf16405b96d21554bc59f07a65523&v=4 url: https://github.com/yourkin - - login: jmagnusson - avatarUrl: https://avatars.githubusercontent.com/u/190835?v=4 - url: https://github.com/jmagnusson - - login: sakti - avatarUrl: https://avatars.githubusercontent.com/u/196178?u=0110be74c4270244546f1b610334042cd16bb8ad&v=4 - url: https://github.com/sakti - login: slafs avatarUrl: https://avatars.githubusercontent.com/u/210173?v=4 url: https://github.com/slafs + - login: assem-ch + avatarUrl: https://avatars.githubusercontent.com/u/315228?u=e0c5ab30726d3243a40974bb9bae327866e42d9b&v=4 + url: https://github.com/assem-ch - login: adamghill avatarUrl: https://avatars.githubusercontent.com/u/317045?u=f1349d5ffe84a19f324e204777859fbf69ddf633&v=4 url: https://github.com/adamghill @@ -245,135 +374,216 @@ sponsors: - login: dmig avatarUrl: https://avatars.githubusercontent.com/u/388564?v=4 url: https://github.com/dmig - - login: hongqn - avatarUrl: https://avatars.githubusercontent.com/u/405587?u=470b4c04832e45141fd5264d3354845cc9fc6466&v=4 - url: https://github.com/hongqn - login: rinckd - avatarUrl: https://avatars.githubusercontent.com/u/546002?u=1fcc7e664dc86524a0af6837a0c222829c3fd4e5&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/546002?u=8ec88ab721a5636346f19dcd677a6f323058be8b&v=4 url: https://github.com/rinckd + - login: securancy + avatarUrl: https://avatars.githubusercontent.com/u/606673?v=4 + url: https://github.com/securancy + - login: falkben + avatarUrl: https://avatars.githubusercontent.com/u/653031?u=0c8d8f33d87f1aa1a6488d3f02105e9abc838105&v=4 + url: https://github.com/falkben - login: hardbyte avatarUrl: https://avatars.githubusercontent.com/u/855189?u=aa29e92f34708814d6b67fcd47ca4cf2ce1c04ed&v=4 url: https://github.com/hardbyte + - login: browniebroke + avatarUrl: https://avatars.githubusercontent.com/u/861044?u=5abfca5588f3e906b31583d7ee62f6de4b68aa24&v=4 + url: https://github.com/browniebroke + - login: janfilips + avatarUrl: https://avatars.githubusercontent.com/u/870699?u=6034d81731ecb41ae5c717e56a901ed46fc039a8&v=4 + url: https://github.com/janfilips + - login: woodrad + avatarUrl: https://avatars.githubusercontent.com/u/1410765?u=86707076bb03d143b3b11afc1743d2aa496bd8bf&v=4 + url: https://github.com/woodrad - login: Pytlicek avatarUrl: https://avatars.githubusercontent.com/u/1430522?u=169dba3bfbc04ed214a914640ff435969f19ddb3&v=4 url: https://github.com/Pytlicek - - login: okken - avatarUrl: https://avatars.githubusercontent.com/u/1568356?u=0a991a21bdc62e2bea9ad311652f2c45f453dc84&v=4 - url: https://github.com/okken + - login: allen0125 + avatarUrl: https://avatars.githubusercontent.com/u/1448456?u=dc2ad819497eef494b88688a1796e0adb87e7cae&v=4 + url: https://github.com/allen0125 + - login: WillHogan + avatarUrl: https://avatars.githubusercontent.com/u/1661551?u=7036c064cf29781470573865264ec8e60b6b809f&v=4 + url: https://github.com/WillHogan - login: cbonoz avatarUrl: https://avatars.githubusercontent.com/u/2351087?u=fd3e8030b2cc9fbfbb54a65e9890c548a016f58b&v=4 url: https://github.com/cbonoz - - login: Abbe98 - avatarUrl: https://avatars.githubusercontent.com/u/2631719?u=8a064aba9a710229ad28c616549d81a24191a5df&v=4 - url: https://github.com/Abbe98 - login: rglsk avatarUrl: https://avatars.githubusercontent.com/u/2768101?u=e349c88673f2155fe021331377c656a9d74bcc25&v=4 url: https://github.com/rglsk - - login: Atem18 - avatarUrl: https://avatars.githubusercontent.com/u/2875254?v=4 - url: https://github.com/Atem18 + - login: Debakel + avatarUrl: https://avatars.githubusercontent.com/u/2857237?u=07df6d11c8feef9306d071cb1c1005a2dd596585&v=4 + url: https://github.com/Debakel - login: paul121 avatarUrl: https://avatars.githubusercontent.com/u/3116995?u=6e2d8691cc345e63ee02e4eb4d7cef82b1fcbedc&v=4 url: https://github.com/paul121 - login: igorcorrea avatarUrl: https://avatars.githubusercontent.com/u/3438238?u=c57605077c31a8f7b2341fc4912507f91b4a5621&v=4 url: https://github.com/igorcorrea - - login: anthcor + - login: anthonycorletti avatarUrl: https://avatars.githubusercontent.com/u/3477132?v=4 - url: https://github.com/anthcor - - login: zsinx6 - avatarUrl: https://avatars.githubusercontent.com/u/3532625?u=ba75a5dc744d1116ccfeaaf30d41cb2fe81fe8dd&v=4 - url: https://github.com/zsinx6 + url: https://github.com/anthonycorletti + - login: jonathanhle + avatarUrl: https://avatars.githubusercontent.com/u/3851599?u=76b9c5d2fecd6c3a16e7645231878c4507380d4d&v=4 + url: https://github.com/jonathanhle - login: pawamoy avatarUrl: https://avatars.githubusercontent.com/u/3999221?u=b030e4c89df2f3a36bc4710b925bdeb6745c9856&v=4 url: https://github.com/pawamoy - - login: spyker77 - avatarUrl: https://avatars.githubusercontent.com/u/4953435?u=03c724c6f8fbab5cd6575b810c0c91c652fa4f79&v=4 - url: https://github.com/spyker77 - - login: JonasKs - avatarUrl: https://avatars.githubusercontent.com/u/5310116?u=98a049f3e1491bffb91e1feb7e93def6881a9389&v=4 - url: https://github.com/JonasKs + - login: Alisa-lisa + avatarUrl: https://avatars.githubusercontent.com/u/4137964?u=e7e393504f554f4ff15863a1e01a5746863ef9ce&v=4 + url: https://github.com/Alisa-lisa + - login: danielunderwood + avatarUrl: https://avatars.githubusercontent.com/u/4472301?v=4 + url: https://github.com/danielunderwood + - login: unredundant + avatarUrl: https://avatars.githubusercontent.com/u/5607577?u=57dd0023365bec03f4fc566df6b81bc0a264a47d&v=4 + url: https://github.com/unredundant + - login: Baghdady92 + avatarUrl: https://avatars.githubusercontent.com/u/5708590?v=4 + url: https://github.com/Baghdady92 - login: holec avatarUrl: https://avatars.githubusercontent.com/u/6438041?u=f5af71ec85b3a9d7b8139cb5af0512b02fa9ab1e&v=4 url: https://github.com/holec - - login: BartlomiejRasztabiga - avatarUrl: https://avatars.githubusercontent.com/u/8852711?u=ed213d60f7a423df31ceb1004aa3ec60e612cb98&v=4 - url: https://github.com/BartlomiejRasztabiga + - login: hcristea + avatarUrl: https://avatars.githubusercontent.com/u/7814406?u=61d7a4fcf846983a4606788eac25e1c6c1209ba8&v=4 + url: https://github.com/hcristea + - login: moonape1226 + avatarUrl: https://avatars.githubusercontent.com/u/8532038?u=d9f8b855a429fff9397c3833c2ff83849ebf989d&v=4 + url: https://github.com/moonape1226 - login: davanstrien avatarUrl: https://avatars.githubusercontent.com/u/8995957?u=fb2aad2b52bb4e7b56db6d7c8ecc9ae1eac1b984&v=4 url: https://github.com/davanstrien - - login: and-semakin - avatarUrl: https://avatars.githubusercontent.com/u/9129071?u=ea77ddf7de4bc375d546bf2825ed420eaddb7666&v=4 - url: https://github.com/and-semakin - - login: VivianSolide - avatarUrl: https://avatars.githubusercontent.com/u/9358572?u=ffb2e2ec522a15dcd3f0af1f9fd1df4afe418afa&v=4 - url: https://github.com/VivianSolide + - login: yenchenLiu + avatarUrl: https://avatars.githubusercontent.com/u/9199638?u=8cdf5ae507448430d90f6f3518d1665a23afe99b&v=4 + url: https://github.com/yenchenLiu + - login: xncbf + avatarUrl: https://avatars.githubusercontent.com/u/9462045?u=866a1311e4bd3ec5ae84185c4fcc99f397c883d7&v=4 + url: https://github.com/xncbf + - login: DMantis + avatarUrl: https://avatars.githubusercontent.com/u/9536869?v=4 + url: https://github.com/DMantis - login: hard-coders - avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=f2d3d2038c55d86d7f9348f4e6c5e30191e4ee8b&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4 url: https://github.com/hard-coders - login: satwikkansal avatarUrl: https://avatars.githubusercontent.com/u/10217535?u=b12d6ef74ea297de9e46da6933b1a5b7ba9e6a61&v=4 url: https://github.com/satwikkansal + - login: mntolia + avatarUrl: https://avatars.githubusercontent.com/u/10390224?v=4 + url: https://github.com/mntolia - login: pheanex avatarUrl: https://avatars.githubusercontent.com/u/10408624?u=5b6bab6ee174aa6e991333e06eb29f628741013d&v=4 url: https://github.com/pheanex - - login: wotori - avatarUrl: https://avatars.githubusercontent.com/u/10486621?u=0044c295b91694b8c9bccc0a805681f794250f7b&v=4 - url: https://github.com/wotori - login: JimFawkes avatarUrl: https://avatars.githubusercontent.com/u/12075115?u=dc58ecfd064d72887c34bf500ddfd52592509acd&v=4 url: https://github.com/JimFawkes + - login: giuliano-oliveira + avatarUrl: https://avatars.githubusercontent.com/u/13181797?u=0ef2dfbf7fc9a9726d45c21d32b5d1038a174870&v=4 + url: https://github.com/giuliano-oliveira - login: logan-connolly avatarUrl: https://avatars.githubusercontent.com/u/16244943?u=8ae66dfbba936463cc8aa0dd7a6d2b4c0cc757eb&v=4 url: https://github.com/logan-connolly - - login: iPr0ger - avatarUrl: https://avatars.githubusercontent.com/u/19322290?v=4 - url: https://github.com/iPr0ger + - login: sanghunka + avatarUrl: https://avatars.githubusercontent.com/u/16280020?u=960f5426ae08303229f045b9cc2ed463dcd41c15&v=4 + url: https://github.com/sanghunka + - login: stevenayers + avatarUrl: https://avatars.githubusercontent.com/u/16361214?u=098b797d8d48afb8cd964b717847943b61d24a6d&v=4 + url: https://github.com/stevenayers + - login: cdsre + avatarUrl: https://avatars.githubusercontent.com/u/16945936?v=4 + url: https://github.com/cdsre + - login: jangia + avatarUrl: https://avatars.githubusercontent.com/u/17927101?u=9261b9bb0c3e3bb1ecba43e8915dc58d8c9a077e&v=4 + url: https://github.com/jangia + - login: yannicschroeer + avatarUrl: https://avatars.githubusercontent.com/u/22749683?u=4df05a7296c207b91c5d7c7a11c29df5ab313e2b&v=4 + url: https://github.com/yannicschroeer - login: ghandic avatarUrl: https://avatars.githubusercontent.com/u/23500353?u=e2e1d736f924d9be81e8bfc565b6d8836ba99773&v=4 url: https://github.com/ghandic - - login: MoronVV - avatarUrl: https://avatars.githubusercontent.com/u/24293616?v=4 - url: https://github.com/MoronVV - login: fstau avatarUrl: https://avatars.githubusercontent.com/u/24669867?u=60e7c8c09f8dafabee8fc3edcd6f9e19abbff918&v=4 url: https://github.com/fstau - login: mertguvencli avatarUrl: https://avatars.githubusercontent.com/u/29762151?u=16a906d90df96c8cff9ea131a575c4bc171b1523&v=4 url: https://github.com/mertguvencli - - login: rgreen32 - avatarUrl: https://avatars.githubusercontent.com/u/35779241?u=c9d64ad1ab364b6a1ec8e3d859da9ca802d681d8&v=4 - url: https://github.com/rgreen32 - - login: askurihin - avatarUrl: https://avatars.githubusercontent.com/u/37978981?v=4 - url: https://github.com/askurihin - - login: JitPackJoyride - avatarUrl: https://avatars.githubusercontent.com/u/40203625?u=9638bfeacfa5940358188f8205ce662bba022b53&v=4 - url: https://github.com/JitPackJoyride - - login: es3n1n - avatarUrl: https://avatars.githubusercontent.com/u/40367813?u=e881a3880f1e342d19a1ea7c8e1b6d76c52dc294&v=4 - url: https://github.com/es3n1n + - login: ruizdiazever + avatarUrl: https://avatars.githubusercontent.com/u/29817086?u=2df54af55663d246e3a4dc8273711c37f1adb117&v=4 + url: https://github.com/ruizdiazever + - login: HosamAlmoghraby + avatarUrl: https://avatars.githubusercontent.com/u/32025281?u=aa1b09feabccbf9dc506b81c71155f32d126cefa&v=4 + url: https://github.com/HosamAlmoghraby + - login: engineerjoe440 + avatarUrl: https://avatars.githubusercontent.com/u/33275230?u=eb223cad27017bb1e936ee9b429b450d092d0236&v=4 + url: https://github.com/engineerjoe440 + - login: declon + avatarUrl: https://avatars.githubusercontent.com/u/36180226?v=4 + url: https://github.com/declon + - login: alvarobartt + avatarUrl: https://avatars.githubusercontent.com/u/36760800?u=ac9ccb8b9164eb5fe7d5276142591aa1b8080daf&v=4 + url: https://github.com/alvarobartt + - login: d-e-h-i-o + avatarUrl: https://avatars.githubusercontent.com/u/36816716?v=4 + url: https://github.com/d-e-h-i-o + - login: ww-daniel-mora + avatarUrl: https://avatars.githubusercontent.com/u/38921751?u=ae14bc1e40f2dd5a9c5741fc0b0dffbd416a5fa9&v=4 + url: https://github.com/ww-daniel-mora + - login: rwxd + avatarUrl: https://avatars.githubusercontent.com/u/40308458?u=9ddf8023ca3326381ba8fb77285ae36598a15de3&v=4 + url: https://github.com/rwxd - login: ilias-ant avatarUrl: https://avatars.githubusercontent.com/u/42189572?u=a2d6121bac4d125d92ec207460fa3f1842d37e66&v=4 url: https://github.com/ilias-ant - login: arrrrrmin - avatarUrl: https://avatars.githubusercontent.com/u/43553423?u=05600727f1cfe75f440bb3fddd49bfea84b1e894&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/43553423?u=2a812c1a2ec58227ed01778837f255143de9df97&v=4 url: https://github.com/arrrrrmin + - login: MauriceKuenicke + avatarUrl: https://avatars.githubusercontent.com/u/47433175?u=37455bc95c7851db296ac42626f0cacb77ca2443&v=4 + url: https://github.com/MauriceKuenicke - login: akanz1 avatarUrl: https://avatars.githubusercontent.com/u/51492342?u=2280f57134118714645e16b535c1a37adf6b369b&v=4 url: https://github.com/akanz1 -- - login: leogregianin - avatarUrl: https://avatars.githubusercontent.com/u/1684053?u=94ddd387601bd1805034dbe83e6eba0491c15323&v=4 - url: https://github.com/leogregianin - - login: sadikkuzu - avatarUrl: https://avatars.githubusercontent.com/u/23168063?u=765ed469c44c004560079210ccdad5b29938eaa9&v=4 - url: https://github.com/sadikkuzu + - login: shidenko97 + avatarUrl: https://avatars.githubusercontent.com/u/54946990?u=3fdc0caea36af9217dacf1cc7760c7ed9d67dcfe&v=4 + url: https://github.com/shidenko97 + - login: data-djinn + avatarUrl: https://avatars.githubusercontent.com/u/56449985?u=42146e140806908d49bd59ccc96f222abf587886&v=4 + url: https://github.com/data-djinn + - login: leo-jp-edwards + avatarUrl: https://avatars.githubusercontent.com/u/58213433?u=2c128e8b0794b7a66211cd7d8ebe05db20b7e9c0&v=4 + url: https://github.com/leo-jp-edwards + - login: apar-tiwari + avatarUrl: https://avatars.githubusercontent.com/u/61064197?v=4 + url: https://github.com/apar-tiwari + - login: Vyvy-vi + avatarUrl: https://avatars.githubusercontent.com/u/62864373?u=1a9b0b28779abc2bc9b62cb4d2e44d453973c9c3&v=4 + url: https://github.com/Vyvy-vi + - login: 0417taehyun + avatarUrl: https://avatars.githubusercontent.com/u/63915557?u=47debaa860fd52c9b98c97ef357ddcec3b3fb399&v=4 + url: https://github.com/0417taehyun + - login: realabja + avatarUrl: https://avatars.githubusercontent.com/u/66185192?u=001e2dd9297784f4218997981b4e6fa8357bb70b&v=4 + url: https://github.com/realabja + - login: alessio-proietti + avatarUrl: https://avatars.githubusercontent.com/u/67370599?u=8ac73db1e18e946a7681f173abdb640516f88515&v=4 + url: https://github.com/alessio-proietti + - login: pondDevThai + avatarUrl: https://avatars.githubusercontent.com/u/71592181?u=08af9a59bccfd8f6b101de1005aa9822007d0a44&v=4 + url: https://github.com/pondDevThai + - login: CY0xZ + avatarUrl: https://avatars.githubusercontent.com/u/103884082?u=0b3260c6a1af6268492f69264dbb75989afb155f&v=4 + url: https://github.com/CY0xZ +- - login: backbord + avatarUrl: https://avatars.githubusercontent.com/u/6814946?v=4 + url: https://github.com/backbord + - login: mattwelke + avatarUrl: https://avatars.githubusercontent.com/u/7719209?u=5d963ead289969257190b133250653bd99df06ba&v=4 + url: https://github.com/mattwelke - login: gabrielmbmb - avatarUrl: https://avatars.githubusercontent.com/u/29572918?u=92084ed7242160dee4d20aece923a10c59758ee5&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/29572918?u=6d1e00b5d558e96718312ff910a2318f47cc3145&v=4 url: https://github.com/gabrielmbmb - - login: starhype - avatarUrl: https://avatars.githubusercontent.com/u/36908028?u=6df41f7b62f0f673f1ecbc87e9cbadaa4fcb0767&v=4 - url: https://github.com/starhype - - login: pixel365 - avatarUrl: https://avatars.githubusercontent.com/u/53819609?u=9e0309c5420ec4624aececd3ca2d7105f7f68133&v=4 - url: https://github.com/pixel365 + - login: danburonline + avatarUrl: https://avatars.githubusercontent.com/u/34251194?u=2cad4388c1544e539ecb732d656e42fb07b4ff2d&v=4 + url: https://github.com/danburonline + - login: Moises6669 + avatarUrl: https://avatars.githubusercontent.com/u/66188523?u=81761d977faabab60cba5a06e7d50b44416c0c99&v=4 + url: https://github.com/Moises6669 diff --git a/docs/en/data/people.yml b/docs/en/data/people.yml index ebbe446ee..d804ecabb 100644 --- a/docs/en/data/people.yml +++ b/docs/en/data/people.yml @@ -1,13 +1,13 @@ maintainers: - login: tiangolo - answers: 1237 - prs: 280 - avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=5cad72c846b7aba2e960546af490edc7375dafc4&v=4 + answers: 1265 + prs: 333 + avatarUrl: https://avatars.githubusercontent.com/u/1326112?u=740f11212a731f56798f558ceddb0bd07642afa7&v=4 url: https://github.com/tiangolo experts: - login: Kludex - count: 319 - avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=3682d9b9b93bef272f379ab623dc031c8d71432e&v=4 + count: 360 + avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4 url: https://github.com/Kludex - login: dmontagu count: 262 @@ -29,20 +29,24 @@ experts: count: 130 avatarUrl: https://avatars.githubusercontent.com/u/331403?v=4 url: https://github.com/phy25 -- login: ArcLightSlavik - count: 71 - avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=81a84af39c89b898b0fbc5a04e8834f60f23e55a&v=4 - url: https://github.com/ArcLightSlavik +- login: JarroVGIT + count: 129 + avatarUrl: https://avatars.githubusercontent.com/u/13659033?u=e8bea32d07a5ef72f7dde3b2079ceb714923ca05&v=4 + url: https://github.com/JarroVGIT - login: raphaelauv - count: 68 + count: 77 avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4 url: https://github.com/raphaelauv +- login: ArcLightSlavik + count: 71 + avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4 + url: https://github.com/ArcLightSlavik - login: falkben count: 58 avatarUrl: https://avatars.githubusercontent.com/u/653031?u=0c8d8f33d87f1aa1a6488d3f02105e9abc838105&v=4 url: https://github.com/falkben - login: sm-Fifteen - count: 48 + count: 49 avatarUrl: https://avatars.githubusercontent.com/u/516999?u=437c0c5038558c67e887ccd863c1ba0f846c03da&v=4 url: https://github.com/sm-Fifteen - login: insomnes @@ -50,41 +54,57 @@ experts: avatarUrl: https://avatars.githubusercontent.com/u/16958893?u=f8be7088d5076d963984a21f95f44e559192d912&v=4 url: https://github.com/insomnes - login: Dustyposa - count: 42 + count: 43 avatarUrl: https://avatars.githubusercontent.com/u/27180793?u=5cf2877f50b3eb2bc55086089a78a36f07042889&v=4 url: https://github.com/Dustyposa +- login: iudeen + count: 42 + avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4 + url: https://github.com/iudeen +- login: jgould22 + count: 42 + avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4 + url: https://github.com/jgould22 +- login: adriangb + count: 40 + avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=75087f0cf0e9f725f3cd18a899218b6c63ae60d3&v=4 + url: https://github.com/adriangb - login: includeamin - count: 38 + count: 39 avatarUrl: https://avatars.githubusercontent.com/u/11836741?u=8bd5ef7e62fe6a82055e33c4c0e0a7879ff8cfb6&v=4 url: https://github.com/includeamin - login: STeveShary count: 37 avatarUrl: https://avatars.githubusercontent.com/u/5167622?u=de8f597c81d6336fcebc37b32dfd61a3f877160c&v=4 url: https://github.com/STeveShary +- login: chbndrhnns + count: 34 + avatarUrl: https://avatars.githubusercontent.com/u/7534547?v=4 + url: https://github.com/chbndrhnns - login: prostomarkeloff count: 33 avatarUrl: https://avatars.githubusercontent.com/u/28061158?u=72309cc1f2e04e40fa38b29969cb4e9d3f722e7b&v=4 url: https://github.com/prostomarkeloff +- login: frankie567 + count: 31 + avatarUrl: https://avatars.githubusercontent.com/u/1144727?u=85c025e3fcc7bd79a5665c63ee87cdf8aae13374&v=4 + url: https://github.com/frankie567 - login: krishnardt count: 31 avatarUrl: https://avatars.githubusercontent.com/u/31960541?u=47f4829c77f4962ab437ffb7995951e41eeebe9b&v=4 url: https://github.com/krishnardt -- login: adriangb - count: 30 - avatarUrl: https://avatars.githubusercontent.com/u/1755071?u=81f0262df34e1460ca546fbd0c211169c2478532&v=4 - url: https://github.com/adriangb - login: wshayes count: 29 avatarUrl: https://avatars.githubusercontent.com/u/365303?u=07ca03c5ee811eb0920e633cc3c3db73dbec1aa5&v=4 url: https://github.com/wshayes -- login: frankie567 - count: 29 - avatarUrl: https://avatars.githubusercontent.com/u/1144727?u=85c025e3fcc7bd79a5665c63ee87cdf8aae13374&v=4 - url: https://github.com/frankie567 -- login: chbndrhnns - count: 25 - avatarUrl: https://avatars.githubusercontent.com/u/7534547?v=4 - url: https://github.com/chbndrhnns +- login: panla + count: 28 + avatarUrl: https://avatars.githubusercontent.com/u/41326348?u=ba2fda6b30110411ecbf406d187907e2b420ac19&v=4 + url: https://github.com/panla +- login: acidjunk + count: 26 + avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4 + url: https://github.com/acidjunk - login: ghandic count: 25 avatarUrl: https://avatars.githubusercontent.com/u/23500353?u=e2e1d736f924d9be81e8bfc565b6d8836ba99773&v=4 @@ -93,10 +113,6 @@ experts: count: 25 avatarUrl: https://avatars.githubusercontent.com/u/43723790?u=9bcce836bbce55835291c5b2ac93a4e311f4b3c3&v=4 url: https://github.com/dbanty -- login: panla - count: 25 - avatarUrl: https://avatars.githubusercontent.com/u/41326348?u=ba2fda6b30110411ecbf406d187907e2b420ac19&v=4 - url: https://github.com/panla - login: SirTelemak count: 24 avatarUrl: https://avatars.githubusercontent.com/u/9435877?u=719327b7d2c4c62212456d771bfa7c6b8dbb9eac&v=4 @@ -113,6 +129,10 @@ experts: count: 21 avatarUrl: https://avatars.githubusercontent.com/u/565544?v=4 url: https://github.com/chris-allnutt +- login: odiseo0 + count: 20 + avatarUrl: https://avatars.githubusercontent.com/u/87550035?u=ab724eae71c3fe1cf81e8dc76e73415da926ef7d&v=4 + url: https://github.com/odiseo0 - login: retnikt count: 19 avatarUrl: https://avatars.githubusercontent.com/u/24581770?v=4 @@ -121,6 +141,10 @@ experts: count: 18 avatarUrl: https://avatars.githubusercontent.com/u/2669034?u=115e53df959309898ad8dc9443fbb35fee71df07&v=4 url: https://github.com/Hultner +- login: rafsaf + count: 18 + avatarUrl: https://avatars.githubusercontent.com/u/51059348?u=f8f0d6d6e90fac39fa786228158ba7f013c74271&v=4 + url: https://github.com/rafsaf - login: jorgerpo count: 17 avatarUrl: https://avatars.githubusercontent.com/u/12537771?u=7444d20019198e34911082780cc7ad73f2b97cb3&v=4 @@ -129,10 +153,10 @@ experts: count: 17 avatarUrl: https://avatars.githubusercontent.com/u/28262306?u=66ee21316275ef356081c2efc4ed7a4572e690dc&v=4 url: https://github.com/nkhitrov -- login: acidjunk - count: 16 - avatarUrl: https://avatars.githubusercontent.com/u/685002?u=b5094ab4527fc84b006c0ac9ff54367bdebb2267&v=4 - url: https://github.com/acidjunk +- login: harunyasar + count: 17 + avatarUrl: https://avatars.githubusercontent.com/u/1765494?u=5b1ab7c582db4b4016fa31affe977d10af108ad4&v=4 + url: https://github.com/harunyasar - login: waynerv count: 16 avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4 @@ -141,90 +165,54 @@ experts: count: 16 avatarUrl: https://avatars.githubusercontent.com/u/41964673?u=9f2174f9d61c15c6e3a4c9e3aeee66f711ce311f&v=4 url: https://github.com/dstlny -- login: jgould22 +- login: jonatasoli + count: 15 + avatarUrl: https://avatars.githubusercontent.com/u/26334101?u=071c062d2861d3dd127f6b4a5258cd8ef55d4c50&v=4 + url: https://github.com/jonatasoli +- login: hellocoldworld count: 14 - avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4 - url: https://github.com/jgould22 -- login: harunyasar - count: 14 - avatarUrl: https://avatars.githubusercontent.com/u/1765494?u=5b1ab7c582db4b4016fa31affe977d10af108ad4&v=4 - url: https://github.com/harunyasar + avatarUrl: https://avatars.githubusercontent.com/u/47581948?u=3d2186796434c507a6cb6de35189ab0ad27c356f&v=4 + url: https://github.com/hellocoldworld - login: haizaar count: 13 avatarUrl: https://avatars.githubusercontent.com/u/58201?u=4f1f9843d69433ca0d380d95146cfe119e5fdac4&v=4 url: https://github.com/haizaar -- login: hellocoldworld - count: 12 - avatarUrl: https://avatars.githubusercontent.com/u/47581948?v=4 - url: https://github.com/hellocoldworld +- login: yinziyan1206 + count: 13 + avatarUrl: https://avatars.githubusercontent.com/u/37829370?v=4 + url: https://github.com/yinziyan1206 +- login: valentin994 + count: 13 + avatarUrl: https://avatars.githubusercontent.com/u/42819267?u=fdeeaa9242a59b243f8603496b00994f6951d5a2&v=4 + url: https://github.com/valentin994 - login: David-Lor count: 12 avatarUrl: https://avatars.githubusercontent.com/u/17401854?u=474680c02b94cba810cb9032fb7eb787d9cc9d22&v=4 url: https://github.com/David-Lor -- login: lowercase00 - count: 11 - avatarUrl: https://avatars.githubusercontent.com/u/21188280?v=4 - url: https://github.com/lowercase00 -- login: zamiramir - count: 11 - avatarUrl: https://avatars.githubusercontent.com/u/40475662?u=e58ef61034e8d0d6a312cc956fb09b9c3332b449&v=4 - url: https://github.com/zamiramir -- login: juntatalor - count: 11 - avatarUrl: https://avatars.githubusercontent.com/u/8134632?v=4 - url: https://github.com/juntatalor -- login: valentin994 - count: 11 - avatarUrl: https://avatars.githubusercontent.com/u/42819267?u=fdeeaa9242a59b243f8603496b00994f6951d5a2&v=4 - url: https://github.com/valentin994 -- login: aalifadv - count: 11 - avatarUrl: https://avatars.githubusercontent.com/u/78442260?v=4 - url: https://github.com/aalifadv -- login: stefanondisponibile - count: 10 - avatarUrl: https://avatars.githubusercontent.com/u/20441825?u=ee1e59446b98f8ec2363caeda4c17164d0d9cc7d&v=4 - url: https://github.com/stefanondisponibile -- login: oligond - count: 10 - avatarUrl: https://avatars.githubusercontent.com/u/2858306?u=1bb1182a5944e93624b7fb26585f22c8f7a9d76e&v=4 - url: https://github.com/oligond +- login: n8sty + count: 12 + avatarUrl: https://avatars.githubusercontent.com/u/2964996?v=4 + url: https://github.com/n8sty +- login: zoliknemet + count: 12 + avatarUrl: https://avatars.githubusercontent.com/u/22326718?u=31ba446ac290e23e56eea8e4f0c558aaf0b40779&v=4 + url: https://github.com/zoliknemet last_month_active: -- login: harunyasar - count: 10 - avatarUrl: https://avatars.githubusercontent.com/u/1765494?u=5b1ab7c582db4b4016fa31affe977d10af108ad4&v=4 - url: https://github.com/harunyasar -- login: jgould22 - count: 10 - avatarUrl: https://avatars.githubusercontent.com/u/4335847?u=ed77f67e0bb069084639b24d812dbb2a2b1dc554&v=4 - url: https://github.com/jgould22 -- login: rafsaf - count: 9 - avatarUrl: https://avatars.githubusercontent.com/u/51059348?u=be9f06b8ced2d2b677297decc781fa8ce4f7ddbd&v=4 - url: https://github.com/rafsaf -- login: STeveShary +- login: JarroVGIT + count: 27 + avatarUrl: https://avatars.githubusercontent.com/u/13659033?u=e8bea32d07a5ef72f7dde3b2079ceb714923ca05&v=4 + url: https://github.com/JarroVGIT +- login: iudeen + count: 17 + avatarUrl: https://avatars.githubusercontent.com/u/10519440?u=2843b3303282bff8b212dcd4d9d6689452e4470c&v=4 + url: https://github.com/iudeen +- login: imacat count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/5167622?u=de8f597c81d6336fcebc37b32dfd61a3f877160c&v=4 - url: https://github.com/STeveShary -- login: ahnaf-zamil - count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/57180217?u=849128b146771ace47beca5b5ff68eb82905dd6d&v=4 - url: https://github.com/ahnaf-zamil -- login: lucastosetto - count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/89307132?u=56326696423df7126c9e7c702ee58f294db69a2a&v=4 - url: https://github.com/lucastosetto -- login: blokje - count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/851418?v=4 - url: https://github.com/blokje -- login: MatthijsKok - count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/7658129?u=1243e32d57e13abc45e3f5235ed5b9197e0d2b41&v=4 - url: https://github.com/MatthijsKok + avatarUrl: https://avatars.githubusercontent.com/u/594968?v=4 + url: https://github.com/imacat - login: Kludex count: 3 - avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=3682d9b9b93bef272f379ab623dc031c8d71432e&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4 url: https://github.com/Kludex top_contributors: - login: waynerv @@ -240,33 +228,37 @@ top_contributors: avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=58ed2a45798a4339700e2f62b2e12e6e54bf0396&v=4 url: https://github.com/dmontagu - login: jaystone776 - count: 15 + count: 16 avatarUrl: https://avatars.githubusercontent.com/u/11191137?u=299205a95e9b6817a43144a48b643346a5aac5cc&v=4 url: https://github.com/jaystone776 - login: euri10 count: 13 avatarUrl: https://avatars.githubusercontent.com/u/1104190?u=321a2e953e6645a7d09b732786c7a8061e0f8a8b&v=4 url: https://github.com/euri10 +- login: Kludex + count: 13 + avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4 + url: https://github.com/Kludex - login: mariacamilagl count: 12 avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4 url: https://github.com/mariacamilagl - login: Smlep - count: 9 + count: 10 avatarUrl: https://avatars.githubusercontent.com/u/16785985?v=4 url: https://github.com/Smlep +- login: dependabot + count: 9 + avatarUrl: https://avatars.githubusercontent.com/in/29110?v=4 + url: https://github.com/apps/dependabot - login: Serrones count: 8 avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4 url: https://github.com/Serrones - login: RunningIkkyu count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=706e1ee3f248245f2d68b976d149d06fd5a2010d&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=efb5b45b55584450507834f279ce48d4d64dea2f&v=4 url: https://github.com/RunningIkkyu -- login: Kludex - count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=3682d9b9b93bef272f379ab623dc031c8d71432e&v=4 - url: https://github.com/Kludex - login: hard-coders count: 7 avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4 @@ -283,6 +275,10 @@ top_contributors: count: 5 avatarUrl: https://avatars.githubusercontent.com/u/1175560?v=4 url: https://github.com/Attsun1031 +- login: ComicShrimp + count: 5 + avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=b3e4d9a14d9a65d429ce62c566aef73178b7111d&v=4 + url: https://github.com/ComicShrimp - login: jekirl count: 4 avatarUrl: https://avatars.githubusercontent.com/u/2546697?u=a027452387d85bd4a14834e19d716c99255fb3b7&v=4 @@ -299,15 +295,35 @@ top_contributors: count: 4 avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4 url: https://github.com/komtaki +- login: hitrust + count: 4 + avatarUrl: https://avatars.githubusercontent.com/u/3360631?u=5fa1f475ad784d64eb9666bdd43cc4d285dcc773&v=4 + url: https://github.com/hitrust +- login: rjNemo + count: 4 + avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4 + url: https://github.com/rjNemo +- login: lsglucas + count: 4 + avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4 + url: https://github.com/lsglucas - login: NinaHwang count: 4 avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=1741703bd6c8f491503354b363a86e879b4c1cab&v=4 url: https://github.com/NinaHwang top_reviewers: - login: Kludex - count: 93 - avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=3682d9b9b93bef272f379ab623dc031c8d71432e&v=4 + count: 96 + avatarUrl: https://avatars.githubusercontent.com/u/7353520?u=62adc405ef418f4b6c8caa93d3eb8ab107bc4927&v=4 url: https://github.com/Kludex +- login: BilalAlpaslan + count: 51 + avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4 + url: https://github.com/BilalAlpaslan +- login: tokusumi + count: 50 + avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4 + url: https://github.com/tokusumi - login: waynerv count: 47 avatarUrl: https://avatars.githubusercontent.com/u/39515546?u=ec35139777597cdbbbddda29bf8b9d4396b429a9&v=4 @@ -316,58 +332,70 @@ top_reviewers: count: 47 avatarUrl: https://avatars.githubusercontent.com/u/59285379?v=4 url: https://github.com/Laineyzhang55 -- login: tokusumi - count: 46 - avatarUrl: https://avatars.githubusercontent.com/u/41147016?u=55010621aece725aa702270b54fed829b6a1fe60&v=4 - url: https://github.com/tokusumi - login: ycd count: 45 avatarUrl: https://avatars.githubusercontent.com/u/62724709?u=826f228edf0bab0d19ad1d5c4ba4df1047ccffef&v=4 url: https://github.com/ycd +- login: cikay + count: 41 + avatarUrl: https://avatars.githubusercontent.com/u/24587499?u=e772190a051ab0eaa9c8542fcff1892471638f2b&v=4 + url: https://github.com/cikay +- login: yezz123 + count: 39 + avatarUrl: https://avatars.githubusercontent.com/u/52716203?u=636b4f79645176df4527dd45c12d5dbb5a4193cf&v=4 + url: https://github.com/yezz123 - login: AdrianDeAnda count: 33 - avatarUrl: https://avatars.githubusercontent.com/u/1024932?u=bb7f8a0d6c9de4e9d0320a9f271210206e202250&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/1024932?u=b2ea249c6b41ddf98679c8d110d0f67d4a3ebf93&v=4 url: https://github.com/AdrianDeAnda - login: ArcLightSlavik count: 31 - avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=81a84af39c89b898b0fbc5a04e8834f60f23e55a&v=4 + avatarUrl: https://avatars.githubusercontent.com/u/31127044?u=b0f2c37142f4b762e41ad65dc49581813422bd71&v=4 url: https://github.com/ArcLightSlavik -- login: cikay - count: 24 - avatarUrl: https://avatars.githubusercontent.com/u/24587499?u=e772190a051ab0eaa9c8542fcff1892471638f2b&v=4 - url: https://github.com/cikay +- login: JarroVGIT + count: 27 + avatarUrl: https://avatars.githubusercontent.com/u/13659033?u=e8bea32d07a5ef72f7dde3b2079ceb714923ca05&v=4 + url: https://github.com/JarroVGIT +- login: cassiobotaro + count: 25 + avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=b0a652331da17efeb85cd6e3a4969182e5004804&v=4 + url: https://github.com/cassiobotaro - login: dmontagu count: 23 avatarUrl: https://avatars.githubusercontent.com/u/35119617?u=58ed2a45798a4339700e2f62b2e12e6e54bf0396&v=4 url: https://github.com/dmontagu -- login: cassiobotaro - count: 23 - avatarUrl: https://avatars.githubusercontent.com/u/3127847?u=b0a652331da17efeb85cd6e3a4969182e5004804&v=4 - url: https://github.com/cassiobotaro - login: komtaki count: 21 avatarUrl: https://avatars.githubusercontent.com/u/39375566?u=260ad6b1a4b34c07dbfa728da5e586f16f6d1824&v=4 url: https://github.com/komtaki - login: hard-coders - count: 19 + count: 20 avatarUrl: https://avatars.githubusercontent.com/u/9651103?u=95db33927bbff1ed1c07efddeb97ac2ff33068ed&v=4 url: https://github.com/hard-coders - login: 0417taehyun count: 19 avatarUrl: https://avatars.githubusercontent.com/u/63915557?u=47debaa860fd52c9b98c97ef357ddcec3b3fb399&v=4 url: https://github.com/0417taehyun +- login: lsglucas + count: 18 + avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4 + url: https://github.com/lsglucas +- login: zy7y + count: 17 + avatarUrl: https://avatars.githubusercontent.com/u/67154681?u=5d634834cc514028ea3f9115f7030b99a1f4d5a4&v=4 + url: https://github.com/zy7y - login: yanever count: 16 avatarUrl: https://avatars.githubusercontent.com/u/21978760?v=4 url: https://github.com/yanever -- login: lsglucas - count: 16 - avatarUrl: https://avatars.githubusercontent.com/u/61513630?u=320e43fe4dc7bc6efc64e9b8f325f8075634fd20&v=4 - url: https://github.com/lsglucas - login: SwftAlpc count: 16 avatarUrl: https://avatars.githubusercontent.com/u/52768429?u=6a3aa15277406520ad37f6236e89466ed44bc5b8&v=4 url: https://github.com/SwftAlpc +- login: rjNemo + count: 16 + avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4 + url: https://github.com/rjNemo - login: Smlep count: 16 avatarUrl: https://avatars.githubusercontent.com/u/16785985?v=4 @@ -384,22 +412,26 @@ top_reviewers: count: 15 avatarUrl: https://avatars.githubusercontent.com/u/63476957?u=6c86e59b48e0394d4db230f37fc9ad4d7e2c27c7&v=4 url: https://github.com/delhi09 -- login: rjNemo - count: 14 - avatarUrl: https://avatars.githubusercontent.com/u/56785022?u=d5c3a02567c8649e146fcfc51b6060ccaf8adef8&v=4 - url: https://github.com/rjNemo -- login: RunningIkkyu - count: 12 - avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=706e1ee3f248245f2d68b976d149d06fd5a2010d&v=4 - url: https://github.com/RunningIkkyu -- login: yezz123 - count: 12 - avatarUrl: https://avatars.githubusercontent.com/u/52716203?u=636b4f79645176df4527dd45c12d5dbb5a4193cf&v=4 - url: https://github.com/yezz123 - login: sh0nk - count: 12 + count: 13 avatarUrl: https://avatars.githubusercontent.com/u/6478810?u=af15d724875cec682ed8088a86d36b2798f981c0&v=4 url: https://github.com/sh0nk +- login: RunningIkkyu + count: 12 + avatarUrl: https://avatars.githubusercontent.com/u/31848542?u=efb5b45b55584450507834f279ce48d4d64dea2f&v=4 + url: https://github.com/RunningIkkyu +- login: odiseo0 + count: 12 + avatarUrl: https://avatars.githubusercontent.com/u/87550035?u=ab724eae71c3fe1cf81e8dc76e73415da926ef7d&v=4 + url: https://github.com/odiseo0 +- login: LorhanSohaky + count: 11 + avatarUrl: https://avatars.githubusercontent.com/u/16273730?u=095b66f243a2cd6a0aadba9a095009f8aaf18393&v=4 + url: https://github.com/LorhanSohaky +- login: solomein-sv + count: 11 + avatarUrl: https://avatars.githubusercontent.com/u/46193920?u=46acfb4aeefb1d7b9fdc5a8cbd9eb8744683c47a&v=4 + url: https://github.com/solomein-sv - login: mariacamilagl count: 10 avatarUrl: https://avatars.githubusercontent.com/u/11489395?u=4adb6986bf3debfc2b8216ae701f2bd47d73da7d&v=4 @@ -412,6 +444,10 @@ top_reviewers: count: 10 avatarUrl: https://avatars.githubusercontent.com/u/7887703?v=4 url: https://github.com/maoyibo +- login: ComicShrimp + count: 10 + avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=b3e4d9a14d9a65d429ce62c566aef73178b7111d&v=4 + url: https://github.com/ComicShrimp - login: graingert count: 9 avatarUrl: https://avatars.githubusercontent.com/u/413772?v=4 @@ -424,42 +460,46 @@ top_reviewers: count: 9 avatarUrl: https://avatars.githubusercontent.com/u/49435654?v=4 url: https://github.com/kty4119 -- login: zy7y - count: 9 - avatarUrl: https://avatars.githubusercontent.com/u/67154681?u=5d634834cc514028ea3f9115f7030b99a1f4d5a4&v=4 - url: https://github.com/zy7y - login: bezaca count: 9 avatarUrl: https://avatars.githubusercontent.com/u/69092910?u=4ac58eab99bd37d663f3d23551df96d4fbdbf760&v=4 url: https://github.com/bezaca -- login: solomein-sv - count: 9 - avatarUrl: https://avatars.githubusercontent.com/u/46193920?u=46acfb4aeefb1d7b9fdc5a8cbd9eb8744683c47a&v=4 - url: https://github.com/solomein-sv +- login: izaguerreiro + count: 8 + avatarUrl: https://avatars.githubusercontent.com/u/2241504?v=4 + url: https://github.com/izaguerreiro +- login: raphaelauv + count: 8 + avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4 + url: https://github.com/raphaelauv - login: blt232018 count: 8 avatarUrl: https://avatars.githubusercontent.com/u/43393471?u=172b0e0391db1aa6c1706498d6dfcb003c8a4857&v=4 url: https://github.com/blt232018 -- login: ComicShrimp +- login: rogerbrinkmann count: 8 - avatarUrl: https://avatars.githubusercontent.com/u/43503750?u=b3e4d9a14d9a65d429ce62c566aef73178b7111d&v=4 - url: https://github.com/ComicShrimp + avatarUrl: https://avatars.githubusercontent.com/u/5690226?v=4 + url: https://github.com/rogerbrinkmann +- login: NinaHwang + count: 8 + avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=1741703bd6c8f491503354b363a86e879b4c1cab&v=4 + url: https://github.com/NinaHwang +- login: dimaqq + count: 8 + avatarUrl: https://avatars.githubusercontent.com/u/662249?v=4 + url: https://github.com/dimaqq - login: Serrones count: 7 avatarUrl: https://avatars.githubusercontent.com/u/22691749?u=4795b880e13ca33a73e52fc0ef7dc9c60c8fce47&v=4 url: https://github.com/Serrones +- login: jovicon + count: 7 + avatarUrl: https://avatars.githubusercontent.com/u/21287303?u=b049eac3e51a4c0473c2efe66b4d28a7d8f2b572&v=4 + url: https://github.com/jovicon - login: ryuckel count: 7 avatarUrl: https://avatars.githubusercontent.com/u/36391432?u=094eec0cfddd5013f76f31e55e56147d78b19553&v=4 url: https://github.com/ryuckel -- login: raphaelauv - count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/10202690?u=e6f86f5c0c3026a15d6b51792fa3e532b12f1371&v=4 - url: https://github.com/raphaelauv -- login: BilalAlpaslan - count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/47563997?u=63ed66e304fe8d765762c70587d61d9196e5c82d&v=4 - url: https://github.com/BilalAlpaslan - login: NastasiaSaby count: 7 avatarUrl: https://avatars.githubusercontent.com/u/8245071?u=b3afd005f9e4bf080c219ef61a592b3a8004b764&v=4 @@ -468,35 +508,3 @@ top_reviewers: count: 7 avatarUrl: https://avatars.githubusercontent.com/u/1405026?v=4 url: https://github.com/Mause -- login: krocdort - count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/34248814?v=4 - url: https://github.com/krocdort -- login: dimaqq - count: 7 - avatarUrl: https://avatars.githubusercontent.com/u/662249?v=4 - url: https://github.com/dimaqq -- login: jovicon - count: 6 - avatarUrl: https://avatars.githubusercontent.com/u/21287303?u=b049eac3e51a4c0473c2efe66b4d28a7d8f2b572&v=4 - url: https://github.com/jovicon -- login: NinaHwang - count: 6 - avatarUrl: https://avatars.githubusercontent.com/u/79563565?u=1741703bd6c8f491503354b363a86e879b4c1cab&v=4 - url: https://github.com/NinaHwang -- login: diogoduartec - count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/31852339?u=b50fc11c531e9b77922e19edfc9e7233d4d7b92e&v=4 - url: https://github.com/diogoduartec -- login: n25a - count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/49960770?u=eb3c95338741c78fff7d9d5d7ace9617e53eee4a&v=4 - url: https://github.com/n25a -- login: izaguerreiro - count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/2241504?v=4 - url: https://github.com/izaguerreiro -- login: israteneda - count: 5 - avatarUrl: https://avatars.githubusercontent.com/u/20668624?u=d7b2961d330aca65fbce5bdb26a0800a3d23ed2d&v=4 - url: https://github.com/israteneda diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml index b98e68b65..749f528c5 100644 --- a/docs/en/data/sponsors.yml +++ b/docs/en/data/sponsors.yml @@ -1,13 +1,16 @@ gold: - - url: https://bit.ly/2QSouzH - title: "Jina: build neural search-as-a-service for any kind of data in just minutes." - img: https://fastapi.tiangolo.com/img/sponsors/jina.svg + - url: https://bit.ly/3dmXC5S + title: The data structure for unstructured multimodal data + img: https://fastapi.tiangolo.com/img/sponsors/docarray.svg + - url: https://bit.ly/3JJ7y5C + title: Build cross-modal and multimodal applications on the cloud + img: https://fastapi.tiangolo.com/img/sponsors/jina2.svg - url: https://cryptapi.io/ title: "CryptAPI: Your easy to use, secure and privacy oriented payment gateway." img: https://fastapi.tiangolo.com/img/sponsors/cryptapi.svg - - url: https://www.dropbase.io/careers - title: Dropbase - seamlessly collect, clean, and centralize data. - img: https://fastapi.tiangolo.com/img/sponsors/dropbase.svg + - url: https://doist.com/careers/9B437B1615-wa-senior-backend-engineer-python + title: Help us migrate doist to FastAPI + img: https://fastapi.tiangolo.com/img/sponsors/doist.svg silver: - url: https://www.deta.sh/?ref=fastapi title: The launchpad for all your (team's) ideas @@ -15,10 +18,7 @@ silver: - url: https://www.investsuite.com/jobs title: Wealthtech jobs with FastAPI img: https://fastapi.tiangolo.com/img/sponsors/investsuite.svg - - url: https://www.vim.so/?utm_source=FastAPI - title: We help you master vim with interactive exercises - img: https://fastapi.tiangolo.com/img/sponsors/vimso.png - - url: https://talkpython.fm/fastapi-sponsor + - url: https://training.talkpython.fm/fastapi-courses title: FastAPI video courses on demand from people you trust img: https://fastapi.tiangolo.com/img/sponsors/talkpython.png - url: https://testdriven.io/courses/tdd-fastapi/ @@ -27,7 +27,16 @@ silver: - url: https://github.com/deepset-ai/haystack/ title: Build powerful search from composable, open source building blocks img: https://fastapi.tiangolo.com/img/sponsors/haystack-fastapi.svg + - url: https://www.udemy.com/course/fastapi-rest/ + title: Learn FastAPI by building a complete project. Extend your knowledge on advanced web development-AWS, Payments, Emails. + img: https://fastapi.tiangolo.com/img/sponsors/ines-course.jpg + - url: https://careers.budget-insight.com/ + title: Budget Insight is hiring! + img: https://fastapi.tiangolo.com/img/sponsors/budget-insight.svg bronze: - - url: https://calmcode.io - title: Code. Simply. Clearly. Calmly. - img: https://fastapi.tiangolo.com/img/sponsors/calmcode.jpg + - url: https://www.exoflare.com/open-source/?utm_source=FastAPI&utm_campaign=open_source + title: Biosecurity risk assessments made easy. + img: https://fastapi.tiangolo.com/img/sponsors/exoflare.png + - url: https://bit.ly/3ccLCmM + title: https://striveworks.us/careers + img: https://fastapi.tiangolo.com/img/sponsors/striveworks2.png diff --git a/docs/en/data/sponsors_badge.yml b/docs/en/data/sponsors_badge.yml index 0c4e716d7..a8bfb0b1b 100644 --- a/docs/en/data/sponsors_badge.yml +++ b/docs/en/data/sponsors_badge.yml @@ -2,9 +2,14 @@ logins: - jina-ai - deta - investsuite - - vimsoHQ - mikeckennedy - - koaning - deepset-ai - cryptapi + - Striveworks + - xoflare + - InesIvanova - DropbaseHQ + - VincentParedes + - BLUE-DEVIL1134 + - ObliviousAI + - Doist diff --git a/docs/en/docs/advanced/additional-responses.md b/docs/en/docs/advanced/additional-responses.md index 4b8b3b71e..dca5f6a98 100644 --- a/docs/en/docs/advanced/additional-responses.md +++ b/docs/en/docs/advanced/additional-responses.md @@ -23,7 +23,7 @@ Each of those response `dict`s can have a key `model`, containing a Pydantic mod For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write: -```Python hl_lines="18 23" +```Python hl_lines="18 22" {!../../../docs_src/additional_responses/tutorial001.py!} ``` @@ -36,7 +36,7 @@ For example, to declare another response with a status code `404` and a Pydantic **FastAPI** will take the Pydantic model from there, generate the `JSON Schema`, and put it in the correct place. The correct place is: - + * In the key `content`, that has as value another JSON object (`dict`) that contains: * A key with the media type, e.g. `application/json`, that contains as value another JSON object, that contains: * A key `schema`, that has as the value the JSON Schema from the model, here's the correct place. diff --git a/docs/en/docs/advanced/additional-status-codes.md b/docs/en/docs/advanced/additional-status-codes.md index eb6031953..b61f88b93 100644 --- a/docs/en/docs/advanced/additional-status-codes.md +++ b/docs/en/docs/advanced/additional-status-codes.md @@ -14,7 +14,7 @@ But you also want it to accept new items. And when the items didn't exist before To achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want: -```Python hl_lines="4 23" +```Python hl_lines="4 25" {!../../../docs_src/additional_status_codes/tutorial001.py!} ``` @@ -22,7 +22,7 @@ To achieve that, import `JSONResponse`, and return your content there directly, When you return a `Response` directly, like in the example above, it will be returned directly. It won't be serialized with a model, etc. - + Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`). !!! note "Technical Details" diff --git a/docs/en/docs/advanced/async-tests.md b/docs/en/docs/advanced/async-tests.md index d5116233f..e34f48f17 100644 --- a/docs/en/docs/advanced/async-tests.md +++ b/docs/en/docs/advanced/async-tests.md @@ -26,13 +26,23 @@ The important difference for us is that with HTTPX we are not limited to synchro ## Example -For a simple example, let's consider the following `main.py` module: +For a simple example, let's consider a file structure similar to the one described in [Bigger Applications](../tutorial/bigger-applications.md){.internal-link target=_blank} and [Testing](../tutorial/testing.md){.internal-link target=_blank}: + +``` +. +├── app +│   ├── __init__.py +│   ├── main.py +│   └── test_main.py +``` + +The file `main.py` would have: ```Python {!../../../docs_src/async_tests/main.py!} ``` -The `test_main.py` module that contains the tests for `main.py` could look like this now: +The file `test_main.py` would have the tests for `main.py`, it could look like this now: ```Python {!../../../docs_src/async_tests/test_main.py!} diff --git a/docs/en/docs/advanced/custom-response.md b/docs/en/docs/advanced/custom-response.md index 546adad2a..ce2619e8d 100644 --- a/docs/en/docs/advanced/custom-response.md +++ b/docs/en/docs/advanced/custom-response.md @@ -21,6 +21,12 @@ For example, if you are squeezing performance, you can install and use `orjson`, but with some custom settings not used in the included `ORJSONResponse` class. + +Let's say you want it to return indented and formatted JSON, so you want to use the orjson option `orjson.OPT_INDENT_2`. + +You could create a `CustomORJSONResponse`. The main thing you have to do is create a `Response.render(content)` method that returns the content as `bytes`: + +```Python hl_lines="9-14 17" +{!../../../docs_src/custom_response/tutorial009c.py!} +``` + +Now instead of returning: + +```json +{"message": "Hello World"} +``` + +...this response will return: + +```json +{ + "message": "Hello World" +} +``` + +Of course, you will probably find much better ways to take advantage of this than formatting JSON. 😉 + ## Default response class When creating a **FastAPI** class instance or an `APIRouter` you can specify which response class to use by default. diff --git a/docs/en/docs/advanced/dataclasses.md b/docs/en/docs/advanced/dataclasses.md index 80a063bb8..72daca06a 100644 --- a/docs/en/docs/advanced/dataclasses.md +++ b/docs/en/docs/advanced/dataclasses.md @@ -8,7 +8,7 @@ But FastAPI also supports using internal support for `dataclasses`. +This is still supported thanks to **Pydantic**, as it has internal support for `dataclasses`. So, even with the code above that doesn't use Pydantic explicitly, FastAPI is using Pydantic to convert those standard dataclasses to Pydantic's own flavor of dataclasses. diff --git a/docs/en/docs/advanced/extending-openapi.md b/docs/en/docs/advanced/extending-openapi.md index d1b14bc00..36619696b 100644 --- a/docs/en/docs/advanced/extending-openapi.md +++ b/docs/en/docs/advanced/extending-openapi.md @@ -132,8 +132,8 @@ You can probably right-click each link and select an option similar to `Save lin **Swagger UI** uses the files: -* `swagger-ui-bundle.js` -* `swagger-ui.css` +* `swagger-ui-bundle.js` +* `swagger-ui.css` And **ReDoc** uses the file: diff --git a/docs/en/docs/advanced/generate-clients.md b/docs/en/docs/advanced/generate-clients.md new file mode 100644 index 000000000..f31a248d0 --- /dev/null +++ b/docs/en/docs/advanced/generate-clients.md @@ -0,0 +1,267 @@ +# Generate Clients + +As **FastAPI** is based on the OpenAPI specification, you get automatic compatibility with many tools, including the automatic API docs (provided by Swagger UI). + +One particular advantage that is not necessarily obvious is that you can **generate clients** (sometimes called **SDKs** ) for your API, for many different **programming languages**. + +## OpenAPI Client Generators + +There are many tools to generate clients from **OpenAPI**. + +A common tool is OpenAPI Generator. + +If you are building a **frontend**, a very interesting alternative is openapi-typescript-codegen. + +## Generate a TypeScript Frontend Client + +Let's start with a simple FastAPI application: + +=== "Python 3.6 and above" + + ```Python hl_lines="9-11 14-15 18 19 23" + {!> ../../../docs_src/generate_clients/tutorial001.py!} + ``` + +=== "Python 3.9 and above" + + ```Python hl_lines="7-9 12-13 16-17 21" + {!> ../../../docs_src/generate_clients/tutorial001_py39.py!} + ``` + +Notice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`. + +### API Docs + +If you go to the API docs, you will see that it has the **schemas** for the data to be sent in requests and received in responses: + + + +You can see those schemas because they were declared with the models in the app. + +That information is available in the app's **OpenAPI schema**, and then shown in the API docs (by Swagger UI). + +And that same information from the models that is included in OpenAPI is what can be used to **generate the client code**. + +### Generate a TypeScript Client + +Now that we have the app with the models, we can generate the client code for the frontend. + +#### Install `openapi-typescript-codegen` + +You can install `openapi-typescript-codegen` in your frontend code with: + +
+ +```console +$ npm install openapi-typescript-codegen --save-dev + +---> 100% +``` + +
+ +#### Generate Client Code + +To generate the client code you can use the command line application `openapi` that would now be installed. + +Because it is installed in the local project, you probably wouldn't be able to call that command directly, but you would put it on your `package.json` file. + +It could look like this: + +```JSON hl_lines="7" +{ + "name": "frontend-app", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "generate-client": "openapi --input http://localhost:8000/openapi.json --output ./src/client --client axios" + }, + "author": "", + "license": "", + "devDependencies": { + "openapi-typescript-codegen": "^0.20.1", + "typescript": "^4.6.2" + } +} +``` + +After having that NPM `generate-client` script there, you can run it with: + +
+ +```console +$ npm run generate-client + +frontend-app@1.0.0 generate-client /home/user/code/frontend-app +> openapi --input http://localhost:8000/openapi.json --output ./src/client --client axios +``` + +
+ +That command will generate code in `./src/client` and will use `axios` (the frontend HTTP library) internally. + +### Try Out the Client Code + +Now you can import and use the client code, it could look like this, notice that you get autocompletion for the methods: + + + +You will also get autocompletion for the payload to send: + + + +!!! tip + Notice the autocompletion for `name` and `price`, that was defined in the FastAPI application, in the `Item` model. + +You will have inline errors for the data that you send: + + + +The response object will also have autocompletion: + + + +## FastAPI App with Tags + +In many cases your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*. + +For example, you could have a section for **items** and another section for **users**, and they could be separated by tags: + + +=== "Python 3.6 and above" + + ```Python hl_lines="23 28 36" + {!> ../../../docs_src/generate_clients/tutorial002.py!} + ``` + +=== "Python 3.9 and above" + + ```Python hl_lines="21 26 34" + {!> ../../../docs_src/generate_clients/tutorial002_py39.py!} + ``` + +### Generate a TypeScript Client with Tags + +If you generate a client for a FastAPI app using tags, it will normally also separate the client code based on the tags. + +This way you will be able to have things ordered and grouped correctly for the client code: + + + +In this case you have: + +* `ItemsService` +* `UsersService` + +### Client Method Names + +Right now the generated method names like `createItemItemsPost` don't look very clean: + +```TypeScript +ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) +``` + +...that's because the client generator uses the OpenAPI internal **operation ID** for each *path operation*. + +OpenAPI requires that each operation ID is unique across all the *path operations*, so FastAPI uses the **function name**, the **path**, and the **HTTP method/operation** to generate that operation ID, because that way it can make sure that the operation IDs are unique. + +But I'll show you how to improve that next. 🤓 + +## Custom Operation IDs and Better Method Names + +You can **modify** the way these operation IDs are **generated** to make them simpler and have **simpler method names** in the clients. + +In this case you will have to ensure that each operation ID is **unique** in some other way. + +For example, you could make sure that each *path operation* has a tag, and then generate the operation ID based on the **tag** and the *path operation* **name** (the function name). + +### Custom Generate Unique ID Function + +FastAPI uses a **unique ID** for each *path operation*, it is used for the **operation ID** and also for the names of any needed custom models, for requests or responses. + +You can customize that function. It takes an `APIRoute` and outputs a string. + +For example, here it is using the first tag (you will probably have only one tag) and the *path operation* name (the function name). + +You can then pass that custom function to **FastAPI** as the `generate_unique_id_function` parameter: + +=== "Python 3.6 and above" + + ```Python hl_lines="8-9 12" + {!> ../../../docs_src/generate_clients/tutorial003.py!} + ``` + +=== "Python 3.9 and above" + + ```Python hl_lines="6-7 10" + {!> ../../../docs_src/generate_clients/tutorial003_py39.py!} + ``` + +### Generate a TypeScript Client with Custom Operation IDs + +Now if you generate the client again, you will see that it has the improved method names: + + + +As you see, the method names now have the tag and then the function name, now they don't include information from the URL path and the HTTP operation. + +### Preprocess the OpenAPI Specification for the Client Generator + +The generated code still has some **duplicated information**. + +We already know that this method is related to the **items** because that word is in the `ItemsService` (taken from the tag), but we still have the tag name prefixed in the method name too. 😕 + +We will probably still want to keep it for OpenAPI in general, as that will ensure that the operation IDs are **unique**. + +But for the generated client we could **modify** the OpenAPI operation IDs right before generating the clients, just to make those method names nicer and **cleaner**. + +We could download the OpenAPI JSON to a file `openapi.json` and then we could **remove that prefixed tag** with a script like this: + +```Python +{!../../../docs_src/generate_clients/tutorial004.py!} +``` + +With that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names. + +### Generate a TypeScript Client with the Preprocessed OpenAPI + +Now as the end result is in a file `openapi.json`, you would modify the `package.json` to use that local file, for example: + +```JSON hl_lines="7" +{ + "name": "frontend-app", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "generate-client": "openapi --input ./openapi.json --output ./src/client --client axios" + }, + "author": "", + "license": "", + "devDependencies": { + "openapi-typescript-codegen": "^0.20.1", + "typescript": "^4.6.2" + } +} +``` + +After generating the new client, you would now have **clean method names**, with all the **autocompletion**, **inline errors**, etc: + + + +## Benefits + +When using the automatically generated clients you would **autocompletion** for: + +* Methods. +* Request payloads in the body, query parameters, etc. +* Response payloads. + +You would also have **inline errors** for everything. + +And whenever you update the backend code, and **regenerate** the frontend, it would have any new *path operations* available as methods, the old ones removed, and any other change would be reflected on the generated code. 🤓 + +This also means that if something changed it will be **reflected** on the client code automatically. And if you **build** the client it will error out if you have any **mismatch** in the data used. + +So, you would **detect many errors** very early in the development cycle instead of having to wait for the errors to show up to your final users in production and then trying to debug where the problem is. ✨ diff --git a/docs/en/docs/advanced/openapi-callbacks.md b/docs/en/docs/advanced/openapi-callbacks.md index 138c90dd7..656ddbb3f 100644 --- a/docs/en/docs/advanced/openapi-callbacks.md +++ b/docs/en/docs/advanced/openapi-callbacks.md @@ -31,7 +31,7 @@ It will have a *path operation* that will receive an `Invoice` body, and a query This part is pretty normal, most of the code is probably already familiar to you: -```Python hl_lines="10-14 37-54" +```Python hl_lines="9-13 36-53" {!../../../docs_src/openapi_callbacks/tutorial001.py!} ``` @@ -83,7 +83,7 @@ So we are going to use that same knowledge to document how the *external API* sh First create a new `APIRouter` that will contain one or more callbacks. -```Python hl_lines="5 26" +```Python hl_lines="3 25" {!../../../docs_src/openapi_callbacks/tutorial001.py!} ``` @@ -96,7 +96,7 @@ It should look just like a normal FastAPI *path operation*: * It should probably have a declaration of the body it should receive, e.g. `body: InvoiceEvent`. * And it could also have a declaration of the response it should return, e.g. `response_model=InvoiceEventReceived`. -```Python hl_lines="17-19 22-23 29-33" +```Python hl_lines="16-18 21-22 28-32" {!../../../docs_src/openapi_callbacks/tutorial001.py!} ``` @@ -163,7 +163,7 @@ At this point you have the *callback path operation(s)* needed (the one(s) that Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` (that's actually just a `list` of routes/*path operations*) from that callback router: -```Python hl_lines="36" +```Python hl_lines="35" {!../../../docs_src/openapi_callbacks/tutorial001.py!} ``` diff --git a/docs/en/docs/advanced/security/http-basic-auth.md b/docs/en/docs/advanced/security/http-basic-auth.md index 6c589cd9a..90c516808 100644 --- a/docs/en/docs/advanced/security/http-basic-auth.md +++ b/docs/en/docs/advanced/security/http-basic-auth.md @@ -34,13 +34,19 @@ Here's a more complete example. Use a dependency to check if the username and password are correct. -For this, use the Python standard module `secrets` to check the username and password: +For this, use the Python standard module `secrets` to check the username and password. -```Python hl_lines="1 11-13" +`secrets.compare_digest()` needs to take `bytes` or a `str` that only contains ASCII characters (the ones in English), this means it wouldn't work with characters like `á`, as in `Sebastián`. + +To handle that, we first convert the `username` and `password` to `bytes` encoding them with UTF-8. + +Then we can use `secrets.compare_digest()` to ensure that `credentials.username` is `"stanleyjobson"`, and that `credentials.password` is `"swordfish"`. + +```Python hl_lines="1 11-21" {!../../../docs_src/security/tutorial007.py!} ``` -This will ensure that `credentials.username` is `"stanleyjobson"`, and that `credentials.password` is `"swordfish"`. This would be similar to: +This would be similar to: ```Python if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): @@ -102,6 +108,6 @@ That way, using `secrets.compare_digest()` in your application code, it will be After detecting that the credentials are incorrect, return an `HTTPException` with a status code 401 (the same returned when no credentials are provided) and add the header `WWW-Authenticate` to make the browser show the login prompt again: -```Python hl_lines="15-19" +```Python hl_lines="23-27" {!../../../docs_src/security/tutorial007.py!} ``` diff --git a/docs/en/docs/advanced/security/oauth2-scopes.md b/docs/en/docs/advanced/security/oauth2-scopes.md index 4bd9cfd04..be51325cd 100644 --- a/docs/en/docs/advanced/security/oauth2-scopes.md +++ b/docs/en/docs/advanced/security/oauth2-scopes.md @@ -16,11 +16,11 @@ In this section you will see how to manage authentication and authorization with You don't necessarily need OAuth2 scopes, and you can handle authentication and authorization however you want. But OAuth2 with scopes can be nicely integrated into your API (with OpenAPI) and your API docs. - + Nevertheless, you still enforce those scopes, or any other security/authorization requirement, however you need, in your code. In many cases, OAuth2 with scopes can be an overkill. - + But if you know you need it, or you are curious, keep reading. ## OAuth2 scopes and OpenAPI @@ -47,7 +47,7 @@ They are normally used to declare specific security permissions, for example: In OAuth2 a "scope" is just a string that declares a specific permission required. It doesn't matter if it has other characters like `:` or if it is a URL. - + Those details are implementation specific. For OAuth2 they are just strings. @@ -115,7 +115,7 @@ In this case, it requires the scope `me` (it could require more than one scope). !!! note You don't necessarily need to add different scopes in different places. - + We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels. ```Python hl_lines="4 139 166" diff --git a/docs/en/docs/advanced/sql-databases-peewee.md b/docs/en/docs/advanced/sql-databases-peewee.md index 48514d1e2..b4ea61367 100644 --- a/docs/en/docs/advanced/sql-databases-peewee.md +++ b/docs/en/docs/advanced/sql-databases-peewee.md @@ -182,7 +182,7 @@ Now let's check the file `sql_app/schemas.py`. To avoid confusion between the Peewee *models* and the Pydantic *models*, we will have the file `models.py` with the Peewee models, and the file `schemas.py` with the Pydantic models. These Pydantic models define more or less a "schema" (a valid data shape). - + So this will help us avoiding confusion while using both. ### Create the Pydantic *models* / schemas diff --git a/docs/en/docs/advanced/testing-dependencies.md b/docs/en/docs/advanced/testing-dependencies.md index 79208e8dc..7bba82fb7 100644 --- a/docs/en/docs/advanced/testing-dependencies.md +++ b/docs/en/docs/advanced/testing-dependencies.md @@ -28,7 +28,7 @@ To override a dependency for testing, you put as a key the original dependency ( And then **FastAPI** will call that override instead of the original dependency. -```Python hl_lines="26-27 30" +```Python hl_lines="28-29 32" {!../../../docs_src/dependency_testing/tutorial001.py!} ``` diff --git a/docs/en/docs/advanced/websockets.md b/docs/en/docs/advanced/websockets.md index 878ad37dd..0e9bc5b06 100644 --- a/docs/en/docs/advanced/websockets.md +++ b/docs/en/docs/advanced/websockets.md @@ -2,6 +2,20 @@ You can use WebSockets with **FastAPI**. +## Install `WebSockets` + +First you need to install `WebSockets`: + +
+ +```console +$ pip install websockets + +---> 100% +``` + +
+ ## WebSockets client ### In production diff --git a/docs/en/docs/alternatives.md b/docs/en/docs/alternatives.md index 28d0be8cc..68aa3150d 100644 --- a/docs/en/docs/alternatives.md +++ b/docs/en/docs/alternatives.md @@ -235,7 +235,7 @@ It was one of the first extremely fast Python frameworks based on `asyncio`. It !!! check "Inspired **FastAPI** to" Find a way to have a crazy performance. - + That's why **FastAPI** is based on Starlette, as it is the fastest framework available (tested by third-party benchmarks). ### Falcon @@ -333,7 +333,7 @@ Now APIStar is a set of tools to validate OpenAPI specifications, not a web fram Exist. The idea of declaring multiple things (data validation, serialization and documentation) with the same Python types, that at the same time provided great editor support, was something I considered a brilliant idea. - + And after searching for a long time for a similar framework and testing many different alternatives, APIStar was the best option available. Then APIStar stopped to exist as a server and Starlette was created, and was a new better foundation for such a system. That was the final inspiration to build **FastAPI**. @@ -391,7 +391,7 @@ That's one of the main things that **FastAPI** adds on top, all based on Python Handle all the core web parts. Adding features on top. The class `FastAPI` itself inherits directly from the class `Starlette`. - + So, anything that you can do with Starlette, you can do it directly with **FastAPI**, as it is basically Starlette on steroids. ### Uvicorn diff --git a/docs/en/docs/async.md b/docs/en/docs/async.md index 8194650fd..c14a2cbb7 100644 --- a/docs/en/docs/async.md +++ b/docs/en/docs/async.md @@ -26,7 +26,7 @@ async def read_results(): --- -If you are using a third party library that communicates with something (a database, an API, the file system, etc) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your *path operation functions* as normally, with just `def`, like: +If you are using a third party library that communicates with something (a database, an API, the file system, etc.) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your *path operation functions* as normally, with just `def`, like: ```Python hl_lines="2" @app.get('/') @@ -45,7 +45,7 @@ If you just don't know, use normal `def`. --- -**Note**: you can mix `def` and `async def` in your *path operation functions* as much as you need and define each one using the best option for you. FastAPI will do the right thing with them. +**Note**: You can mix `def` and `async def` in your *path operation functions* as much as you need and define each one using the best option for you. FastAPI will do the right thing with them. Anyway, in any of the cases above, FastAPI will still work asynchronously and be extremely fast. @@ -102,87 +102,117 @@ To see the difference, imagine the following story about burgers: ### Concurrent Burgers - +You go with your crush to get fast food, you stand in line while the cashier takes the orders from the people in front of you. 😍 -You go with your crush 😍 to get fast food 🍔, you stand in line while the cashier 💁 takes the orders from the people in front of you. + -Then it's your turn, you place your order of 2 very fancy burgers 🍔 for your crush 😍 and you. +Then it's your turn, you place your order of 2 very fancy burgers for your crush and you. 🍔🍔 -You pay 💸. + -The cashier 💁 says something to the cook in the kitchen 👨‍🍳 so they know they have to prepare your burgers 🍔 (even though they are currently preparing the ones for the previous clients). +The cashier says something to the cook in the kitchen so they know they have to prepare your burgers (even though they are currently preparing the ones for the previous clients). -The cashier 💁 gives you the number of your turn. + -While you are waiting, you go with your crush 😍 and pick a table, you sit and talk with your crush 😍 for a long time (as your burgers are very fancy and take some time to prepare ✨🍔✨). +You pay. 💸 -As you are sitting on the table with your crush 😍, while you wait for the burgers 🍔, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨. +The cashier gives you the number of your turn. -While waiting and talking to your crush 😍, from time to time, you check the number displayed on the counter to see if it's your turn already. + -Then at some point, it finally is your turn. You go to the counter, get your burgers 🍔 and come back to the table. +While you are waiting, you go with your crush and pick a table, you sit and talk with your crush for a long time (as your burgers are very fancy and take some time to prepare). -You and your crush 😍 eat the burgers 🍔 and have a nice time ✨. +As you are sitting at the table with your crush, while you wait for the burgers, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨. + + + +While waiting and talking to your crush, from time to time, you check the number displayed on the counter to see if it's your turn already. + +Then at some point, it finally is your turn. You go to the counter, get your burgers and come back to the table. + + + +You and your crush eat the burgers and have a nice time. ✨ + + + +!!! info + Beautiful illustrations by Ketrina Thompson. 🎨 --- Imagine you are the computer / program 🤖 in that story. -While you are at the line, you are just idle 😴, waiting for your turn, not doing anything very "productive". But the line is fast because the cashier 💁 is only taking the orders (not preparing them), so that's fine. +While you are at the line, you are just idle 😴, waiting for your turn, not doing anything very "productive". But the line is fast because the cashier is only taking the orders (not preparing them), so that's fine. -Then, when it's your turn, you do actual "productive" work 🤓, you process the menu, decide what you want, get your crush's 😍 choice, pay 💸, check that you give the correct bill or card, check that you are charged correctly, check that the order has the correct items, etc. +Then, when it's your turn, you do actual "productive" work, you process the menu, decide what you want, get your crush's choice, pay, check that you give the correct bill or card, check that you are charged correctly, check that the order has the correct items, etc. -But then, even though you still don't have your burgers 🍔, your work with the cashier 💁 is "on pause" ⏸, because you have to wait 🕙 for your burgers to be ready. +But then, even though you still don't have your burgers, your work with the cashier is "on pause" ⏸, because you have to wait 🕙 for your burgers to be ready. -But as you go away from the counter and sit on the table with a number for your turn, you can switch 🔀 your attention to your crush 😍, and "work" ⏯ 🤓 on that. Then you are again doing something very "productive" 🤓, as is flirting with your crush 😍. +But as you go away from the counter and sit at the table with a number for your turn, you can switch 🔀 your attention to your crush, and "work" ⏯ 🤓 on that. Then you are again doing something very "productive" as is flirting with your crush 😍. -Then the cashier 💁 says "I'm finished with doing the burgers" 🍔 by putting your number on the counter's display, but you don't jump like crazy immediately when the displayed number changes to your turn number. You know no one will steal your burgers 🍔 because you have the number of your turn, and they have theirs. +Then the cashier 💁 says "I'm finished with doing the burgers" by putting your number on the counter's display, but you don't jump like crazy immediately when the displayed number changes to your turn number. You know no one will steal your burgers because you have the number of your turn, and they have theirs. -So you wait for your crush 😍 to finish the story (finish the current work ⏯ / task being processed 🤓), smile gently and say that you are going for the burgers ⏸. +So you wait for your crush to finish the story (finish the current work ⏯ / task being processed 🤓), smile gently and say that you are going for the burgers ⏸. -Then you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers 🍔, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of "eating burgers" 🔀 ⏯, but the previous one of "getting burgers" is finished ⏹. +Then you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of "eating burgers" 🔀 ⏯, but the previous one of "getting burgers" is finished ⏹. ### Parallel Burgers Now let's imagine these aren't "Concurrent Burgers", but "Parallel Burgers". -You go with your crush 😍 to get parallel fast food 🍔. +You go with your crush to get parallel fast food. -You stand in line while several (let's say 8) cashiers that at the same time are cooks 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳 take the orders from the people in front of you. +You stand in line while several (let's say 8) cashiers that at the same time are cooks take the orders from the people in front of you. -Everyone before you is waiting 🕙 for their burgers 🍔 to be ready before leaving the counter because each of the 8 cashiers goes and prepares the burger right away before getting the next order. +Everyone before you is waiting for their burgers to be ready before leaving the counter because each of the 8 cashiers goes and prepares the burger right away before getting the next order. -Then it's finally your turn, you place your order of 2 very fancy burgers 🍔 for your crush 😍 and you. + + +Then it's finally your turn, you place your order of 2 very fancy burgers for your crush and you. You pay 💸. -The cashier goes to the kitchen 👨‍🍳. + -You wait, standing in front of the counter 🕙, so that no one else takes your burgers 🍔 before you do, as there are no numbers for turns. +The cashier goes to the kitchen. -As you and your crush 😍 are busy not letting anyone get in front of you and take your burgers whenever they arrive 🕙, you cannot pay attention to your crush 😞. +You wait, standing in front of the counter 🕙, so that no one else takes your burgers before you do, as there are no numbers for turns. -This is "synchronous" work, you are "synchronized" with the cashier/cook 👨‍🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨‍🍳 finishes the burgers 🍔 and gives them to you, or otherwise, someone else might take them. + -Then your cashier/cook 👨‍🍳 finally comes back with your burgers 🍔, after a long time waiting 🕙 there in front of the counter. +As you and your crush are busy not letting anyone get in front of you and take your burgers whenever they arrive, you cannot pay attention to your crush. 😞 -You take your burgers 🍔 and go to the table with your crush 😍. +This is "synchronous" work, you are "synchronized" with the cashier/cook 👨‍🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨‍🍳 finishes the burgers and gives them to you, or otherwise, someone else might take them. -You just eat them, and you are done 🍔 ⏹. + -There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter 😞. +Then your cashier/cook 👨‍🍳 finally comes back with your burgers, after a long time waiting 🕙 there in front of the counter. + + + +You take your burgers and go to the table with your crush. + +You just eat them, and you are done. ⏹ + + + +There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter. 😞 + +!!! info + Beautiful illustrations by Ketrina Thompson. 🎨 --- -In this scenario of the parallel burgers, you are a computer / program 🤖 with two processors (you and your crush 😍), both waiting 🕙 and dedicating their attention ⏯ to be "waiting on the counter" 🕙 for a long time. +In this scenario of the parallel burgers, you are a computer / program 🤖 with two processors (you and your crush), both waiting 🕙 and dedicating their attention ⏯ to be "waiting on the counter" 🕙 for a long time. -The fast food store has 8 processors (cashiers/cooks) 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳. While the concurrent burgers store might have had only 2 (one cashier and one cook) 💁 👨‍🍳. +The fast food store has 8 processors (cashiers/cooks). While the concurrent burgers store might have had only 2 (one cashier and one cook). -But still, the final experience is not the best 😞. +But still, the final experience is not the best. 😞 --- -This would be the parallel equivalent story for burgers 🍔. +This would be the parallel equivalent story for burgers. 🍔 For a more "real life" example of this, imagine a bank. @@ -208,11 +238,7 @@ This "waiting" 🕙 is measured in microseconds, but still, summing it all, it's That's why it makes a lot of sense to use asynchronous ⏸🔀⏯ code for web APIs. -Most of the existing popular Python frameworks (including Flask and Django) were created before the new asynchronous features in Python existed. So, the ways they can be deployed support parallel execution and an older form of asynchronous execution that is not as powerful as the new capabilities. - -Even though the main specification for asynchronous web Python (ASGI) was developed at Django, to add support for WebSockets. - -That kind of asynchronicity is what made NodeJS popular (even though NodeJS is not parallel) and that's the strength of Go as a programming language. +This kind of asynchronicity is what made NodeJS popular (even though NodeJS is not parallel) and that's the strength of Go as a programming language. And that's the same level of performance you get with **FastAPI**. @@ -238,7 +264,7 @@ You could have turns as in the burgers example, first the living room, then the It would take the same amount of time to finish with or without turns (concurrency) and you would have done the same amount of work. -But in this case, if you could bring the 8 ex-cashier/cooks/now-cleaners 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, and each one of them (plus you) could take a zone of the house to clean it, you could do all the work in **parallel**, with the extra help, and finish much sooner. +But in this case, if you could bring the 8 ex-cashier/cooks/now-cleaners, and each one of them (plus you) could take a zone of the house to clean it, you could do all the work in **parallel**, with the extra help, and finish much sooner. In this scenario, each one of the cleaners (including you) would be a processor, doing their part of the job. @@ -371,7 +397,7 @@ All that is what powers FastAPI (through Starlette) and what makes it have such These are very technical details of how **FastAPI** works underneath. - If you have quite some technical knowledge (co-routines, threads, blocking, etc) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead. + If you have quite some technical knowledge (co-routines, threads, blocking, etc.) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead. ### Path operation functions diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index 648c472fe..ca51c6e82 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -84,7 +84,17 @@ To check it worked, use: If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉 +Make sure you have the latest pip version on your virtual environment to avoid errors on the next steps: +
+ +```console +$ python -m pip install --upgrade pip + +---> 100% +``` + +
!!! tip Every time you install a new package with `pip` under that environment, activate the environment again. diff --git a/docs/en/docs/css/custom.css b/docs/en/docs/css/custom.css index 7d3503e49..066b51725 100644 --- a/docs/en/docs/css/custom.css +++ b/docs/en/docs/css/custom.css @@ -4,10 +4,21 @@ display: block; } +.termy { + /* For right to left languages */ + direction: ltr; +} + .termy [data-termynal] { white-space: pre-wrap; } +a.external-link { + /* For right to left languages */ + direction: ltr; + display: inline-block; +} + a.external-link::after { /* \00A0 is a non-breaking space to make the mark be on the same line as the link @@ -94,7 +105,7 @@ a.announce-link:hover { .announce-wrapper .sponsor-badge { display: block; position: absolute; - top: -5px; + top: -10px; right: 0; font-size: 0.5rem; color: #999; @@ -118,3 +129,18 @@ a.announce-link:hover { .twitter { color: #00acee; } + +/* Right to left languages */ +code { + direction: ltr; + display: inline-block; +} + +.md-content__inner h1 { + direction: ltr !important; +} + +.illustration { + margin-top: 2em; + margin-bottom: 2em; +} diff --git a/docs/en/docs/deployment/docker.md b/docs/en/docs/deployment/docker.md index 3f86efcce..8a542622e 100644 --- a/docs/en/docs/deployment/docker.md +++ b/docs/en/docs/deployment/docker.md @@ -142,7 +142,7 @@ Successfully installed fastapi pydantic uvicorn * Create a `main.py` file with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -155,7 +155,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -350,7 +350,7 @@ If your FastAPI is a single file, for example, `main.py` without an `./app` dire Then you would just have to change the corresponding paths to copy the file inside the `Dockerfile`: ```{ .dockerfile .annotate hl_lines="10 13" } -FROM python:3.9 +FROM python:3.9 WORKDIR /code diff --git a/docs/en/docs/deployment/manually.md b/docs/en/docs/deployment/manually.md index 7fd1f4d4f..d6892b2c1 100644 --- a/docs/en/docs/deployment/manually.md +++ b/docs/en/docs/deployment/manually.md @@ -38,7 +38,7 @@ You can install an ASGI compatible server with: !!! tip By adding the `standard`, Uvicorn will install and use some recommended extra dependencies. - + That including `uvloop`, the high-performance drop-in replacement for `asyncio`, that provides the big concurrency performance boost. === "Hypercorn" @@ -59,7 +59,7 @@ You can install an ASGI compatible server with: ## Run the Server Program -You can then your application the same way you have done in the tutorials, but without the `--reload` option, e.g.: +You can then run your application the same way you have done in the tutorials, but without the `--reload` option, e.g.: === "Uvicorn" @@ -89,7 +89,7 @@ You can then your application the same way you have done in the tutorials, but w Remember to remove the `--reload` option if you were using it. The `--reload` option consumes much more resources, is more unstable, etc. - + It helps a lot during **development**, but you **shouldn't** use it in **production**. ## Hypercorn with Trio diff --git a/docs/en/docs/features.md b/docs/en/docs/features.md index 36f80783a..02bb3ac1f 100644 --- a/docs/en/docs/features.md +++ b/docs/en/docs/features.md @@ -190,11 +190,11 @@ With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on * Plays nicely with your **IDE/linter/brain**: * Because pydantic data structures are just instances of classes you define; auto-completion, linting, mypy and your intuition should all work properly with your validated data. * **Fast**: - * in benchmarks Pydantic is faster than all other tested libraries. + * in benchmarks Pydantic is faster than all other tested libraries. * Validate **complex structures**: * Use of hierarchical Pydantic models, Python `typing`’s `List` and `Dict`, etc. * And validators allow complex data schemas to be clearly and easily defined, checked and documented as JSON Schema. * You can have deeply **nested JSON** objects and have them all validated and annotated. -* **Extendible**: +* **Extensible**: * Pydantic allows custom data types to be defined or you can extend validation with methods on a model decorated with the validator decorator. * 100% test coverage. diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-01.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-01.png new file mode 100644 index 000000000..e0e77d3fc Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-01.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-02.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-02.png new file mode 100644 index 000000000..27f6e1271 Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-02.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-03.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-03.png new file mode 100644 index 000000000..27472a8e0 Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-03.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-04.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-04.png new file mode 100644 index 000000000..cf1d8dd45 Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-04.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-05.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-05.png new file mode 100644 index 000000000..ab6e03669 Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-05.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-06.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-06.png new file mode 100644 index 000000000..4bbf247c0 Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-06.png differ diff --git a/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-07.png b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-07.png new file mode 100644 index 000000000..7a0f4092d Binary files /dev/null and b/docs/en/docs/img/async/concurrent-burgers/concurrent-burgers-07.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-01.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-01.png new file mode 100644 index 000000000..92fc1a8a0 Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-01.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-02.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-02.png new file mode 100644 index 000000000..9583b84dc Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-02.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-03.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-03.png new file mode 100644 index 000000000..bea9ff0d8 Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-03.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-04.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-04.png new file mode 100644 index 000000000..b5c8a60bb Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-04.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-05.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-05.png new file mode 100644 index 000000000..45aca8e21 Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-05.png differ diff --git a/docs/en/docs/img/async/parallel-burgers/parallel-burgers-06.png b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-06.png new file mode 100644 index 000000000..c91c4b472 Binary files /dev/null and b/docs/en/docs/img/async/parallel-burgers/parallel-burgers-06.png differ diff --git a/docs/en/docs/img/deployment/concepts/process-ram.drawio b/docs/en/docs/img/deployment/concepts/process-ram.drawio index 51fc30ed3..b29c8a342 100644 --- a/docs/en/docs/img/deployment/concepts/process-ram.drawio +++ b/docs/en/docs/img/deployment/concepts/process-ram.drawio @@ -103,4 +103,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/concepts/process-ram.svg b/docs/en/docs/img/deployment/concepts/process-ram.svg index cd086c36b..c1bf0d589 100644 --- a/docs/en/docs/img/deployment/concepts/process-ram.svg +++ b/docs/en/docs/img/deployment/concepts/process-ram.svg @@ -56,4 +56,4 @@ }
Server
Server
RAM
RAM
CPU
CPU -
Process Manager
Process Manager
Worker Process
Worker Process
Worker Process
Worker Process
Another Process
Another Process
1 GB
1 GB
1 GB
1 GBViewer does not support full SVG 1.1 \ No newline at end of file +
Process Manager
Process Manager
Worker Process
Worker Process
Worker Process
Worker Process
Another Process
Another Process
1 GB
1 GB
1 GB
1 GBViewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https.drawio b/docs/en/docs/img/deployment/https/https.drawio index 31cfab96b..c4c8a3628 100644 --- a/docs/en/docs/img/deployment/https/https.drawio +++ b/docs/en/docs/img/deployment/https/https.drawio @@ -274,4 +274,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https.svg b/docs/en/docs/img/deployment/https/https.svg index e63345eba..69497518a 100644 --- a/docs/en/docs/img/deployment/https/https.svg +++ b/docs/en/docs/img/deployment/https/https.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...
Decrypted request for: someapp.example.com
Decrypted request for: someapp.example.comViewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...
Decrypted request for: someapp.example.com
Decrypted request for: someapp.example.comViewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https01.drawio b/docs/en/docs/img/deployment/https/https01.drawio index 9bc5340ce..181582f9b 100644 --- a/docs/en/docs/img/deployment/https/https01.drawio +++ b/docs/en/docs/img/deployment/https/https01.drawio @@ -75,4 +75,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https01.svg b/docs/en/docs/img/deployment/https/https01.svg index 4fee0adfc..2edbd0623 100644 --- a/docs/en/docs/img/deployment/https/https01.svg +++ b/docs/en/docs/img/deployment/https/https01.svg @@ -54,4 +54,4 @@ src: url("https://fonts.gstatic.com/s/roboto/v29/KFOmCnqEu92Fr1Mu4mxK.woff2") format('woff2'); unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; } -
https://someapp.example.com
https://someapp.example.com
DNS Servers
DNS Servers
Who is: someapp.example.com
Who is: someapp.example.com
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
https://someapp.example.com
https://someapp.example.com
DNS Servers
DNS Servers
Who is: someapp.example.com
Who is: someapp.example.com
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https02.drawio b/docs/en/docs/img/deployment/https/https02.drawio index 0f7578d3e..650c06d1e 100644 --- a/docs/en/docs/img/deployment/https/https02.drawio +++ b/docs/en/docs/img/deployment/https/https02.drawio @@ -107,4 +107,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https02.svg b/docs/en/docs/img/deployment/https/https02.svg index 1f37a7098..e16b7e94a 100644 --- a/docs/en/docs/img/deployment/https/https02.svg +++ b/docs/en/docs/img/deployment/https/https02.svg @@ -54,4 +54,4 @@ src: url("https://fonts.gstatic.com/s/roboto/v29/KFOmCnqEu92Fr1Mu4mxK.woff2") format('woff2'); unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; } -
Server(s)
Server(s)
https://someapp.example.com
https://someapp.example.com
DNS Servers
DNS Servers
Port 443 (HTTPS)
Port 443 (HTTPS)
IP:
123.124.125.126
IP:...
Who is: someapp.example.com
Who is: someapp.example.com
IP:
123.124.125.126
IP:...
TLS Handshake
TLS HandshakeViewer does not support full SVG 1.1 \ No newline at end of file +
Server(s)
Server(s)
https://someapp.example.com
https://someapp.example.com
DNS Servers
DNS Servers
Port 443 (HTTPS)
Port 443 (HTTPS)
IP:
123.124.125.126
IP:...
Who is: someapp.example.com
Who is: someapp.example.com
IP:
123.124.125.126
IP:...
TLS Handshake
TLS HandshakeViewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https03.drawio b/docs/en/docs/img/deployment/https/https03.drawio index c5766086c..c178fd363 100644 --- a/docs/en/docs/img/deployment/https/https03.drawio +++ b/docs/en/docs/img/deployment/https/https03.drawio @@ -128,4 +128,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https03.svg b/docs/en/docs/img/deployment/https/https03.svg index e68e1c459..2badd1c7d 100644 --- a/docs/en/docs/img/deployment/https/https03.svg +++ b/docs/en/docs/img/deployment/https/https03.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https04.drawio b/docs/en/docs/img/deployment/https/https04.drawio index ea357a6c1..78a6e919a 100644 --- a/docs/en/docs/img/deployment/https/https04.drawio +++ b/docs/en/docs/img/deployment/https/https04.drawio @@ -149,4 +149,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https04.svg b/docs/en/docs/img/deployment/https/https04.svg index 4c9b7999b..4513ac76b 100644 --- a/docs/en/docs/img/deployment/https/https04.svg +++ b/docs/en/docs/img/deployment/https/https04.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https05.drawio b/docs/en/docs/img/deployment/https/https05.drawio index 9b8b7c6f7..236ecd841 100644 --- a/docs/en/docs/img/deployment/https/https05.drawio +++ b/docs/en/docs/img/deployment/https/https05.drawio @@ -163,4 +163,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https05.svg b/docs/en/docs/img/deployment/https/https05.svg index d11647b9b..ddcd2760a 100644 --- a/docs/en/docs/img/deployment/https/https05.svg +++ b/docs/en/docs/img/deployment/https/https05.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https06.drawio b/docs/en/docs/img/deployment/https/https06.drawio index 5bb85813f..9dec13184 100644 --- a/docs/en/docs/img/deployment/https/https06.drawio +++ b/docs/en/docs/img/deployment/https/https06.drawio @@ -180,4 +180,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https06.svg b/docs/en/docs/img/deployment/https/https06.svg index 10e03b7c5..3695de40c 100644 --- a/docs/en/docs/img/deployment/https/https06.svg +++ b/docs/en/docs/img/deployment/https/https06.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https07.drawio b/docs/en/docs/img/deployment/https/https07.drawio index 1ca994b22..aa8f4d6be 100644 --- a/docs/en/docs/img/deployment/https/https07.drawio +++ b/docs/en/docs/img/deployment/https/https07.drawio @@ -200,4 +200,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https07.svg b/docs/en/docs/img/deployment/https/https07.svg index e409d8871..551354cef 100644 --- a/docs/en/docs/img/deployment/https/https07.svg +++ b/docs/en/docs/img/deployment/https/https07.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/deployment/https/https08.drawio b/docs/en/docs/img/deployment/https/https08.drawio index 8a4f41056..794b192df 100644 --- a/docs/en/docs/img/deployment/https/https08.drawio +++ b/docs/en/docs/img/deployment/https/https08.drawio @@ -214,4 +214,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/deployment/https/https08.svg b/docs/en/docs/img/deployment/https/https08.svg index 3047dd821..2d4680dcc 100644 --- a/docs/en/docs/img/deployment/https/https08.svg +++ b/docs/en/docs/img/deployment/https/https08.svg @@ -59,4 +59,4 @@
someapp.example.com
someapp.example.com
another.example.net
another.example.net
onemore.example.org
onemore.example.org -
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 \ No newline at end of file +
IP:
123.124.125.126
IP:...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/sponsors/budget-insight.svg b/docs/en/docs/img/sponsors/budget-insight.svg new file mode 100644 index 000000000..d753727a1 --- /dev/null +++ b/docs/en/docs/img/sponsors/budget-insight.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/docs/img/sponsors/classiq-banner.png b/docs/en/docs/img/sponsors/classiq-banner.png new file mode 100644 index 000000000..8a0d6ac74 Binary files /dev/null and b/docs/en/docs/img/sponsors/classiq-banner.png differ diff --git a/docs/en/docs/img/sponsors/classiq.png b/docs/en/docs/img/sponsors/classiq.png new file mode 100644 index 000000000..189c6bbe8 Binary files /dev/null and b/docs/en/docs/img/sponsors/classiq.png differ diff --git a/docs/en/docs/img/sponsors/docarray-top-banner.svg b/docs/en/docs/img/sponsors/docarray-top-banner.svg new file mode 100644 index 000000000..b2eca3544 --- /dev/null +++ b/docs/en/docs/img/sponsors/docarray-top-banner.svg @@ -0,0 +1 @@ + diff --git a/docs/en/docs/img/sponsors/docarray.svg b/docs/en/docs/img/sponsors/docarray.svg new file mode 100644 index 000000000..f18df247e --- /dev/null +++ b/docs/en/docs/img/sponsors/docarray.svg @@ -0,0 +1 @@ + diff --git a/docs/en/docs/img/sponsors/doist-banner.svg b/docs/en/docs/img/sponsors/doist-banner.svg new file mode 100644 index 000000000..3a4d9a295 --- /dev/null +++ b/docs/en/docs/img/sponsors/doist-banner.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/docs/img/sponsors/doist.svg b/docs/en/docs/img/sponsors/doist.svg new file mode 100644 index 000000000..b55855f06 --- /dev/null +++ b/docs/en/docs/img/sponsors/doist.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/en/docs/img/sponsors/exoflare.png b/docs/en/docs/img/sponsors/exoflare.png new file mode 100644 index 000000000..b5977d80b Binary files /dev/null and b/docs/en/docs/img/sponsors/exoflare.png differ diff --git a/docs/en/docs/img/sponsors/fastapi-course-bundle-banner.png b/docs/en/docs/img/sponsors/fastapi-course-bundle-banner.png new file mode 100644 index 000000000..220d08638 Binary files /dev/null and b/docs/en/docs/img/sponsors/fastapi-course-bundle-banner.png differ diff --git a/docs/en/docs/img/sponsors/imgwhale-banner.svg b/docs/en/docs/img/sponsors/imgwhale-banner.svg new file mode 100644 index 000000000..db87cc4c9 --- /dev/null +++ b/docs/en/docs/img/sponsors/imgwhale-banner.svg @@ -0,0 +1,14 @@ + + + + + + + + + + ImgWhale + The ultimate solution to unlimited and forevercloud storage. + + diff --git a/docs/en/docs/img/sponsors/imgwhale.svg b/docs/en/docs/img/sponsors/imgwhale.svg new file mode 100644 index 000000000..46aefd930 --- /dev/null +++ b/docs/en/docs/img/sponsors/imgwhale.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + ImgWhale + + The ultimate solution to unlimited and forever cloud storage. + + The ultimate solution to unlimited and forever cloud storage. + + + + diff --git a/docs/en/docs/img/sponsors/ines-course.jpg b/docs/en/docs/img/sponsors/ines-course.jpg new file mode 100644 index 000000000..05158b387 Binary files /dev/null and b/docs/en/docs/img/sponsors/ines-course.jpg differ diff --git a/docs/en/docs/img/sponsors/jina-ai-banner.png b/docs/en/docs/img/sponsors/jina-ai-banner.png new file mode 100644 index 000000000..3ac6b44ad Binary files /dev/null and b/docs/en/docs/img/sponsors/jina-ai-banner.png differ diff --git a/docs/en/docs/img/sponsors/jina-ai.png b/docs/en/docs/img/sponsors/jina-ai.png new file mode 100644 index 000000000..d6b0bfb4e Binary files /dev/null and b/docs/en/docs/img/sponsors/jina-ai.png differ diff --git a/docs/en/docs/img/sponsors/jina-top-banner.svg b/docs/en/docs/img/sponsors/jina-top-banner.svg new file mode 100644 index 000000000..8b62cd619 --- /dev/null +++ b/docs/en/docs/img/sponsors/jina-top-banner.svg @@ -0,0 +1 @@ + diff --git a/docs/en/docs/img/sponsors/jina2.svg b/docs/en/docs/img/sponsors/jina2.svg new file mode 100644 index 000000000..6a48677ba --- /dev/null +++ b/docs/en/docs/img/sponsors/jina2.svg @@ -0,0 +1 @@ + diff --git a/docs/en/docs/img/sponsors/striveworks-banner.png b/docs/en/docs/img/sponsors/striveworks-banner.png new file mode 100644 index 000000000..5206744b7 Binary files /dev/null and b/docs/en/docs/img/sponsors/striveworks-banner.png differ diff --git a/docs/en/docs/img/sponsors/striveworks.png b/docs/en/docs/img/sponsors/striveworks.png new file mode 100644 index 000000000..435ac536c Binary files /dev/null and b/docs/en/docs/img/sponsors/striveworks.png differ diff --git a/docs/en/docs/img/sponsors/striveworks2.png b/docs/en/docs/img/sponsors/striveworks2.png new file mode 100644 index 000000000..bed9cb0a7 Binary files /dev/null and b/docs/en/docs/img/sponsors/striveworks2.png differ diff --git a/docs/en/docs/img/sponsors/testdriven.svg b/docs/en/docs/img/sponsors/testdriven.svg index 97741b9e0..6ba2daa3b 100644 --- a/docs/en/docs/img/sponsors/testdriven.svg +++ b/docs/en/docs/img/sponsors/testdriven.svg @@ -1 +1 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/tutorial/bigger-applications/package.drawio b/docs/en/docs/img/tutorial/bigger-applications/package.drawio index 48f6e76fe..cab3de2ca 100644 --- a/docs/en/docs/img/tutorial/bigger-applications/package.drawio +++ b/docs/en/docs/img/tutorial/bigger-applications/package.drawio @@ -40,4 +40,4 @@ - \ No newline at end of file + diff --git a/docs/en/docs/img/tutorial/bigger-applications/package.svg b/docs/en/docs/img/tutorial/bigger-applications/package.svg index a9cec926a..44da1dc30 100644 --- a/docs/en/docs/img/tutorial/bigger-applications/package.svg +++ b/docs/en/docs/img/tutorial/bigger-applications/package.svg @@ -1 +1 @@ -
Package app
app/__init__.py
Package app...
Module app.main
app/main.py
Module app.main...
Module app.dependencies
app/dependencies.py
Module app.dependencies...
Subpackage app.internal
app/internal/__init__.py
Subpackage app.internal...
Module app.internal.admin
app/internal/admin.py
Module app.internal.admin...
Subpackage app.routers
app/routers/__init__.py
Subpackage app.routers...
Module app.routers.items
app/routers/items.py
Module app.routers.items...
Module app.routers.users
app/routers/users.py
Module app.routers.users...Viewer does not support full SVG 1.1 \ No newline at end of file +
Package app
app/__init__.py
Package app...
Module app.main
app/main.py
Module app.main...
Module app.dependencies
app/dependencies.py
Module app.dependencies...
Subpackage app.internal
app/internal/__init__.py
Subpackage app.internal...
Module app.internal.admin
app/internal/admin.py
Module app.internal.admin...
Subpackage app.routers
app/routers/__init__.py
Subpackage app.routers...
Module app.routers.items
app/routers/items.py
Module app.routers.items...
Module app.routers.users
app/routers/users.py
Module app.routers.users...Viewer does not support full SVG 1.1 diff --git a/docs/en/docs/img/tutorial/generate-clients/image01.png b/docs/en/docs/img/tutorial/generate-clients/image01.png new file mode 100644 index 000000000..f23d57773 Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image01.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image02.png b/docs/en/docs/img/tutorial/generate-clients/image02.png new file mode 100644 index 000000000..f991352eb Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image02.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image03.png b/docs/en/docs/img/tutorial/generate-clients/image03.png new file mode 100644 index 000000000..e2514b048 Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image03.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image04.png b/docs/en/docs/img/tutorial/generate-clients/image04.png new file mode 100644 index 000000000..777a695bb Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image04.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image05.png b/docs/en/docs/img/tutorial/generate-clients/image05.png new file mode 100644 index 000000000..e1e53179d Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image05.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image06.png b/docs/en/docs/img/tutorial/generate-clients/image06.png new file mode 100644 index 000000000..0e9a100ea Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image06.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image07.png b/docs/en/docs/img/tutorial/generate-clients/image07.png new file mode 100644 index 000000000..27884960f Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image07.png differ diff --git a/docs/en/docs/img/tutorial/generate-clients/image08.png b/docs/en/docs/img/tutorial/generate-clients/image08.png new file mode 100644 index 000000000..509fbd340 Binary files /dev/null and b/docs/en/docs/img/tutorial/generate-clients/image08.png differ diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index 7de1e50df..97ec0ffcf 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -32,7 +32,6 @@ FastAPI is a modern, fast (high-performance), web framework for building APIs wi The key features are: * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). - * **Fast to code**: Increase the speed to develop features by about 200% to 300%. * * **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * * **Intuitive**: Great editor support. Completion everywhere. Less time debugging. @@ -129,7 +128,7 @@ $ pip install fastapi
-You will also need an ASGI server, for production such as Uvicorn or Hypercorn. +You will also need an ASGI server, for production such as Uvicorn or Hypercorn.
@@ -148,7 +147,7 @@ $ pip install "uvicorn[standard]" * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -161,7 +160,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -171,7 +170,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -184,7 +183,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -263,7 +262,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 Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -274,7 +273,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -283,7 +282,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} diff --git a/docs/en/docs/js/termynal.js b/docs/en/docs/js/termynal.js index 8b0e9339e..4ac32708a 100644 --- a/docs/en/docs/js/termynal.js +++ b/docs/en/docs/js/termynal.js @@ -72,14 +72,14 @@ class Termynal { * Initialise the widget, get lines, clear container and start animation. */ init() { - /** + /** * Calculates width and height of Termynal container. * If container is empty and lines are dynamically loaded, defaults to browser `auto` or CSS. - */ + */ const containerStyle = getComputedStyle(this.container); - this.container.style.width = containerStyle.width !== '0px' ? + this.container.style.width = containerStyle.width !== '0px' ? containerStyle.width : undefined; - this.container.style.minHeight = containerStyle.height !== '0px' ? + this.container.style.minHeight = containerStyle.height !== '0px' ? containerStyle.height : undefined; this.container.setAttribute('data-termynal', ''); @@ -138,7 +138,7 @@ class Termynal { restart.innerHTML = "restart ↻" return restart } - + generateFinish() { const finish = document.createElement('a') finish.onclick = (e) => { @@ -215,7 +215,7 @@ class Termynal { /** * Converts line data objects into line elements. - * + * * @param {Object[]} lineData - Dynamically loaded lines. * @param {Object} line - Line data object. * @returns {Element[]} - Array of line elements. @@ -231,7 +231,7 @@ class Termynal { /** * Helper function for generating attributes string. - * + * * @param {Object} line - Line data object. * @returns {string} - String of attributes. */ diff --git a/docs/en/docs/python-types.md b/docs/en/docs/python-types.md index fe56dadec..3d22ee620 100644 --- a/docs/en/docs/python-types.md +++ b/docs/en/docs/python-types.md @@ -29,7 +29,7 @@ Calling this program outputs: John Doe ``` -The function does the following: +The function does the following: * Takes a `first_name` and `last_name`. * Converts the first letter of each one to upper case with `title()`. @@ -158,7 +158,7 @@ The syntax using `typing` is **compatible** with all versions, from Python 3.6 t As Python advances, **newer versions** come with improved support for these type annotations and in many cases you won't even need to import and use the `typing` module to declare the type annotations. -If you can chose a more recent version of Python for your project, you will be able to take advantage of that extra simplicity. See some examples below. +If you can choose a more recent version of Python for your project, you will be able to take advantage of that extra simplicity. See some examples below. #### List @@ -267,7 +267,7 @@ You can declare that a variable can be any of **several types**, for example, an In Python 3.6 and above (including Python 3.10) you can use the `Union` type from `typing` and put inside the square brackets the possible types to accept. -In Python 3.10 there's also an **alternative syntax** were you can put the possible types separated by a vertical bar (`|`). +In Python 3.10 there's also an **alternative syntax** where you can put the possible types separated by a vertical bar (`|`). === "Python 3.6 and above" @@ -317,6 +317,45 @@ This also means that in Python 3.10, you can use `Something | None`: {!> ../../../docs_src/python_types/tutorial009_py310.py!} ``` +#### Using `Union` or `Optional` + +If you are using a Python version below 3.10, here's a tip from my very **subjective** point of view: + +* 🚨 Avoid using `Optional[SomeType]` +* Instead ✨ **use `Union[SomeType, None]`** ✨. + +Both are equivalent and underneath they are the same, but I would recommend `Union` instead of `Optional` because the word "**optional**" would seem to imply that the value is optional, and it actually means "it can be `None`", even if it's not optional and is still required. + +I think `Union[SomeType, None]` is more explicit about what it means. + +It's just about the words and names. But those words can affect how you and your teammates think about the code. + +As an example, let's take this function: + +```Python hl_lines="1 4" +{!../../../docs_src/python_types/tutorial009c.py!} +``` + +The parameter `name` is defined as `Optional[str]`, but it is **not optional**, you cannot call the function without the parameter: + +```Python +say_hi() # Oh, no, this throws an error! 😱 +``` + +The `name` parameter is **still required** (not *optional*) because it doesn't have a default value. Still, `name` accepts `None` as the value: + +```Python +say_hi(name=None) # This works, None is valid 🎉 +``` + +The good news is, once you are on Python 3.10 you won't have to worry about that, as you will be able to simply use `|` to define unions of types: + +```Python hl_lines="1 4" +{!../../../docs_src/python_types/tutorial009c_py310.py!} +``` + +And then you won't have to worry about names like `Optional` and `Union`. 😎 + #### Generic types These types that take type parameters in square brackets are called **Generic types** or **Generics**, for example: @@ -333,28 +372,28 @@ These types that take type parameters in square brackets are called **Generic ty === "Python 3.9 and above" - You can use the same builtin types as generics (with square brakets and types inside): - + You can use the same builtin types as generics (with square brackets and types inside): + * `list` * `tuple` * `set` * `dict` And the same as with Python 3.6, from the `typing` module: - + * `Union` * `Optional` * ...and others. === "Python 3.10 and above" - You can use the same builtin types as generics (with square brakets and types inside): + You can use the same builtin types as generics (with square brackets and types inside): * `list` * `tuple` * `set` * `dict` - + And the same as with Python 3.6, from the `typing` module: * `Union` @@ -422,6 +461,9 @@ An example from the official Pydantic docs: You will see a lot more of all this in practice in the [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. +!!! tip + Pydantic has a special behavior when you use `Optional` or `Union[Something, None]` without a default value, you can read more about it in the Pydantic docs about Required Optional fields. + ## Type hints in **FastAPI** **FastAPI** takes advantage of these type hints to do several things. diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 6d5ee8ea1..120b374e2 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -2,7 +2,585 @@ ## Latest Changes + +## 0.83.0 + +🚨 This is probably the last release (or one of the last releases) to support Python 3.6. 🔥 + +Python 3.6 reached the [end-of-life and is no longer supported by Python](https://www.python.org/downloads/release/python-3615/) since around a year ago. + +You hopefully updated to a supported version of Python a while ago. If you haven't, you really should. + +### Features + +* ✨ Add support in `jsonable_encoder` for include and exclude with dataclasses. PR [#4923](https://github.com/tiangolo/fastapi/pull/4923) by [@DCsunset](https://github.com/DCsunset). + +### 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). + +### Docs + +* 📝 Update `SECURITY.md`. PR [#5377](https://github.com/tiangolo/fastapi/pull/5377) by [@Kludex](https://github.com/Kludex). + +### Internal + +* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#5352](https://github.com/tiangolo/fastapi/pull/5352) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci). + +## 0.82.0 + +🚨 This is probably the last release (or one of the last releases) to support Python 3.6. 🔥 + +Python 3.6 reached the [end-of-life and is no longer supported by Python](https://www.python.org/downloads/release/python-3615/) since around a year ago. + +You hopefully updated to a supported version of Python a while ago. If you haven't, you really should. + +### Features + +* ✨ Export `WebSocketState` in `fastapi.websockets`. PR [#4376](https://github.com/tiangolo/fastapi/pull/4376) by [@matiuszka](https://github.com/matiuszka). +* ✨ Support Python internal description on Pydantic model's docstring. PR [#3032](https://github.com/tiangolo/fastapi/pull/3032) by [@Kludex](https://github.com/Kludex). +* ✨ Update `ORJSONResponse` to support non `str` keys and serializing Numpy arrays. PR [#3892](https://github.com/tiangolo/fastapi/pull/3892) by [@baby5](https://github.com/baby5). + +### Fixes + +* 🐛 Allow exit code for dependencies with `yield` to always execute, by removing capacity limiter for them, to e.g. allow closing DB connections without deadlocks. PR [#5122](https://github.com/tiangolo/fastapi/pull/5122) by [@adriangb](https://github.com/adriangb). +* 🐛 Fix FastAPI People GitHub Action: set HTTPX timeout for GraphQL query request. PR [#5222](https://github.com/tiangolo/fastapi/pull/5222) by [@iudeen](https://github.com/iudeen). +* 🐛 Make sure a parameter defined as required is kept required in OpenAPI even if defined as optional in another dependency. PR [#4319](https://github.com/tiangolo/fastapi/pull/4319) by [@cd17822](https://github.com/cd17822). +* 🐛 Fix support for path parameters in WebSockets. PR [#3879](https://github.com/tiangolo/fastapi/pull/3879) by [@davidbrochart](https://github.com/davidbrochart). + +### Docs + +* ✏ Update Hypercorn link, now pointing to GitHub. PR [#5346](https://github.com/tiangolo/fastapi/pull/5346) by [@baconfield](https://github.com/baconfield). +* ✏ Tweak wording in `docs/en/docs/advanced/dataclasses.md`. PR [#3698](https://github.com/tiangolo/fastapi/pull/3698) by [@pfackeldey](https://github.com/pfackeldey). +* 📝 Add note about Python 3.10 `X | Y` operator in explanation about Response Models. PR [#5307](https://github.com/tiangolo/fastapi/pull/5307) by [@MendyLanda](https://github.com/MendyLanda). +* 📝 Add link to New Relic article: "How to monitor FastAPI application performance using Python agent". PR [#5260](https://github.com/tiangolo/fastapi/pull/5260) by [@sjyothi54](https://github.com/sjyothi54). +* 📝 Update docs for `ORJSONResponse` with details about improving performance. PR [#2615](https://github.com/tiangolo/fastapi/pull/2615) by [@falkben](https://github.com/falkben). +* 📝 Add docs for creating a custom Response class. PR [#5331](https://github.com/tiangolo/fastapi/pull/5331) by [@tiangolo](https://github.com/tiangolo). +* 📝 Add tip about using alias for form data fields. PR [#5329](https://github.com/tiangolo/fastapi/pull/5329) by [@tiangolo](https://github.com/tiangolo). + +### Translations + +* 🌐 Add Russian translation for `docs/ru/docs/features.md`. PR [#5315](https://github.com/tiangolo/fastapi/pull/5315) by [@Xewus](https://github.com/Xewus). +* 🌐 Update Chinese translation for `docs/zh/docs/tutorial/request-files.md`. PR [#4529](https://github.com/tiangolo/fastapi/pull/4529) by [@ASpathfinder](https://github.com/ASpathfinder). +* 🌐 Add Chinese translation for `docs/zh/docs/tutorial/encoder.md`. PR [#4969](https://github.com/tiangolo/fastapi/pull/4969) by [@Zssaer](https://github.com/Zssaer). +* 🌐 Fix MkDocs file line for Portuguese translation of `background-task.md`. PR [#5242](https://github.com/tiangolo/fastapi/pull/5242) by [@ComicShrimp](https://github.com/ComicShrimp). + +### Internal + +* 👥 Update FastAPI People. PR [#5347](https://github.com/tiangolo/fastapi/pull/5347) by [@github-actions[bot]](https://github.com/apps/github-actions). +* ⬆ Bump dawidd6/action-download-artifact from 2.22.0 to 2.23.0. PR [#5321](https://github.com/tiangolo/fastapi/pull/5321) by [@dependabot[bot]](https://github.com/apps/dependabot). +* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#5318](https://github.com/tiangolo/fastapi/pull/5318) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci). +* ✏ Fix a small code highlight line error. PR [#5256](https://github.com/tiangolo/fastapi/pull/5256) by [@hjlarry](https://github.com/hjlarry). +* ♻ Internal small refactor, move `operation_id` parameter position in delete method for consistency with the code. PR [#4474](https://github.com/tiangolo/fastapi/pull/4474) by [@hiel](https://github.com/hiel). +* 🔧 Update sponsors, disable ImgWhale. PR [#5338](https://github.com/tiangolo/fastapi/pull/5338) by [@tiangolo](https://github.com/tiangolo). + +## 0.81.0 + +### Features + +* ✨ Add ReDoc `
-
- +
- + - +
@@ -46,12 +40,56 @@
-
- + +
+ + + + +
+
+ + +
{% endblock %} +{%- block scripts %} +{{ super() }} + + + + + + + +{%- endblock %} diff --git a/docs/es/docs/advanced/additional-status-codes.md b/docs/es/docs/advanced/additional-status-codes.md index 67224fb36..1f28ea85b 100644 --- a/docs/es/docs/advanced/additional-status-codes.md +++ b/docs/es/docs/advanced/additional-status-codes.md @@ -14,7 +14,7 @@ Pero también quieres que acepte nuevos ítems. Cuando los ítems no existan ant Para conseguir esto importa `JSONResponse` y devuelve ahí directamente tu contenido, asignando el `status_code` que quieras: -```Python hl_lines="2 19" +```Python hl_lines="4 25" {!../../../docs_src/additional_status_codes/tutorial001.py!} ``` diff --git a/docs/es/docs/features.md b/docs/es/docs/features.md index 945b2cc94..3c59eb88c 100644 --- a/docs/es/docs/features.md +++ b/docs/es/docs/features.md @@ -191,7 +191,7 @@ Con **FastAPI** obtienes todas las características de **Pydantic** (dado que Fa * Interactúa bien con tu **IDE/linter/cerebro**: * Porque las estructuras de datos de Pydantic son solo instances de clases que tu defines, el auto-completado, el linting, mypy y tu intuición deberían funcionar bien con tus datos validados. * **Rápido**: - * En benchmarks Pydantic es más rápido que todas las otras libraries probadas. + * En benchmarks Pydantic es más rápido que todas las otras libraries probadas. * Valida **estructuras complejas**: * Usa modelos jerárquicos de modelos de Pydantic, `typing` de Python, `List` y `Dict`, etc. * Los validadores también permiten que se definan fácil y claramente schemas complejos de datos. Estos son chequeados y documentados como JSON Schema. diff --git a/docs/es/docs/index.md b/docs/es/docs/index.md index 65eaf75d0..44c59202a 100644 --- a/docs/es/docs/index.md +++ b/docs/es/docs/index.md @@ -130,7 +130,7 @@ También vas a necesitar un servidor ASGI para producción cómo ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -145,7 +145,7 @@ $ pip install uvicorn[standard] ```Python from fastapi import FastAPI -from typing import Optional +from typing import Union app = FastAPI() @@ -156,7 +156,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -167,7 +167,7 @@ Si tu código usa `async` / `await`, usa `async def`: ```Python hl_lines="7 12" from fastapi import FastAPI -from typing import Optional +from typing import Union app = FastAPI() @@ -178,7 +178,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -259,7 +259,7 @@ Declara el body usando las declaraciones de tipo estándares de Python gracias a ```Python hl_lines="2 7-10 23-25" from fastapi import FastAPI from pydantic import BaseModel -from typing import Optional +from typing import Union app = FastAPI() @@ -267,7 +267,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -276,7 +276,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -439,7 +439,6 @@ Usadas por Pydantic: Usados por Starlette: * requests - Requerido si quieres usar el `TestClient`. -* aiofiles - Requerido si quieres usar `FileResponse` o `StaticFiles`. * jinja2 - Requerido si quieres usar la configuración por defecto de templates. * python-multipart - Requerido si quieres dar soporte a "parsing" de formularios, con `request.form()`. * itsdangerous - Requerido para dar soporte a `SessionMiddleware`. diff --git a/docs/es/docs/tutorial/first-steps.md b/docs/es/docs/tutorial/first-steps.md index 79f0a51c0..110036e8c 100644 --- a/docs/es/docs/tutorial/first-steps.md +++ b/docs/es/docs/tutorial/first-steps.md @@ -254,7 +254,7 @@ El `@app.get("/")` le dice a **FastAPI** que la función que tiene justo debajo Esa sintaxis `@algo` se llama un "decorador" en Python. Lo pones encima de una función. Es como un lindo sombrero decorado (creo que de ahí salió el concepto). - + Un "decorador" toma la función que tiene debajo y hace algo con ella. En nuestro caso, este decorador le dice a **FastAPI** que la función que está debajo corresponde al **path** `/` con una **operación** `get`. diff --git a/docs/es/docs/tutorial/index.md b/docs/es/docs/tutorial/index.md index 9cbdb2727..e3671f381 100644 --- a/docs/es/docs/tutorial/index.md +++ b/docs/es/docs/tutorial/index.md @@ -41,7 +41,7 @@ Para el tutorial, es posible que quieras instalarlo con todas las dependencias y
```console -$ pip install fastapi[all] +$ pip install "fastapi[all]" ---> 100% ``` @@ -62,7 +62,7 @@ $ pip install fastapi[all] También debes instalar `uvicorn` para que funcione como tu servidor: ``` - pip install uvicorn[standard] + pip install "uvicorn[standard]" ``` Y lo mismo para cada una de las dependencias opcionales que quieras utilizar. diff --git a/docs/es/docs/tutorial/query-params.md b/docs/es/docs/tutorial/query-params.md index 69caee6e8..482af8dc0 100644 --- a/docs/es/docs/tutorial/query-params.md +++ b/docs/es/docs/tutorial/query-params.md @@ -75,7 +75,7 @@ En este caso el parámetro de la función `q` será opcional y será `None` por !!! note "Nota" FastAPI sabrá que `q` es opcional por el `= None`. - El `Optional` en `Optional[str]` no es usado por FastAPI (FastAPI solo usará la parte `str`), pero el `Optional[str]` le permitirá a tu editor ayudarte a encontrar errores en tu código. + El `Union` en `Union[str, None]` no es usado por FastAPI (FastAPI solo usará la parte `str`), pero el `Union[str, None]` le permitirá a tu editor ayudarte a encontrar errores en tu código. ## Conversión de tipos de parámetros de query diff --git a/docs/es/mkdocs.yml b/docs/es/mkdocs.yml index a4bc41154..d1d6215b6 100644 --- a/docs/es/mkdocs.yml +++ b/docs/es/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -79,6 +85,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -107,8 +115,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -117,6 +129,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -125,6 +139,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/fa/docs/index.md b/docs/fa/docs/index.md new file mode 100644 index 000000000..0f7cd569a --- /dev/null +++ b/docs/fa/docs/index.md @@ -0,0 +1,462 @@ +

+ FastAPI +

+

+ فریم‌ورک FastAPI، کارایی بالا، یادگیری آسان، کدنویسی سریع، آماده برای استفاده در محیط پروداکشن +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**مستندات**: https://fastapi.tiangolo.com + +**کد منبع**: https://github.com/tiangolo/fastapi + +--- +FastAPI یک وب فریم‌ورک مدرن و سریع (با کارایی بالا) برای ایجاد APIهای متنوع (وب، وب‌سوکت و غبره) با زبان پایتون نسخه +۳.۶ است. این فریم‌ورک با رعایت کامل راهنمای نوع داده (Type Hint) ایجاد شده است. + +ویژگی‌های کلیدی این فریم‌ورک عبارتند از: + +* **سرعت**: کارایی بسیار بالا و قابل مقایسه با **NodeJS** و **Go** (با تشکر از Starlette و Pydantic). [یکی از سریع‌ترین فریم‌ورک‌های پایتونی موجود](#performance). + +* **کدنویسی سریع**: افزایش ۲۰۰ تا ۳۰۰ درصدی سرعت توسعه فابلیت‌های جدید. * +* **باگ کمتر**: کاهش ۴۰ درصدی خطاهای انسانی (برنامه‌نویسی). * +* **غریزی**: پشتیبانی فوق‌العاده در محیط‌های توسعه یکپارچه (IDE). تکمیل در همه بخش‌های کد. کاهش زمان رفع باگ. +* **آسان**: طراحی شده برای یادگیری و استفاده آسان. کاهش زمان مورد نیاز برای مراجعه به مستندات. +* **کوچک**: کاهش تکرار در کد. چندین قابلیت برای هر پارامتر (منظور پارامترهای ورودی تابع هندلر می‌باشد، به بخش خلاصه در همین صفحه مراجعه شود). باگ کمتر. +* **استوار**: ایجاد کدی آماده برای استفاده در محیط پروداکشن و تولید خودکار مستندات تعاملی +* **مبتنی بر استانداردها**: مبتنی بر (و منطبق با) استانداردهای متن باز مربوط به API: OpenAPI (سوگر سابق) و JSON Schema. + +* تخمین‌ها بر اساس تست‌های انجام شده در یک تیم توسعه داخلی که مشغول ایجاد برنامه‌های کاربردی واقعی بودند صورت گرفته است. + +## اسپانسرهای طلایی + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor %} +{% endif %} + + + +دیگر اسپانسرها + +## نظر دیگران در مورد FastAPI + +
[...] I'm using FastAPI a ton these days. [...] I'm actually planning to use it for all of my team's ML services at Microsoft. Some of them are getting integrated into the core Windows product and some Office products."
+ +
Kabir Khan - Microsoft (ref)
+ +--- + +
"We adopted the FastAPI library to spawn a RESTserver that can be queried to obtain predictions. [for Ludwig]"
+ +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +
"Netflix is pleased to announce the open-source release of our crisis management orchestration framework: Dispatch! [built with FastAPI]"
+ +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +
"I’m over the moon excited about FastAPI. It’s so fun!"
+ +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +
"Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted Hug to be - it's really inspiring to see someone build that."
+ +
Timothy Crosley - Hug creator (ref)
+ +--- + +
"If you're looking to learn one modern framework for building REST APIs, check out FastAPI [...] It's fast, easy to use and easy to learn [...]"
+ +
"We've switched over to FastAPI for our APIs [...] I think you'll like it [...]"
+ +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, فریم‌ورکی معادل FastAPI برای کار با واسط خط فرمان + + + +اگر در حال ساختن برنامه‌ای برای استفاده در CLI (به جای استفاده در وب) هستید، می‌توانید از **Typer**. استفاده کنید. + +**Typer** دوقلوی کوچکتر FastAPI است و قرار است معادلی برای FastAPI در برنامه‌های CLI باشد.️ 🚀 + +## نیازمندی‌ها + +پایتون +۳.۶ + +FastAPI مبتنی بر ابزارهای قدرتمند زیر است: + +* فریم‌ورک Starlette برای بخش وب. +* کتابخانه Pydantic برای بخش داده‌. + +## نصب + +
+ +```console +$ pip install fastapi + +---> 100% +``` + +
+ +نصب یک سرور پروداکشن نظیر Uvicorn یا Hypercorn نیز جزء نیازمندی‌هاست. + +
+ +```console +$ pip install "uvicorn[standard]" + +---> 100% +``` + +
+ +## مثال + +### ایجاد کنید +* فایلی به نام `main.py` با محتوای زیر ایجاد کنید : + +```Python +from typing import Optional + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+همچنین می‌توانید از async def... نیز استفاده کنید + +اگر در کدتان از `async` / `await` استفاده می‌کنید, از `async def` برای تعریف تابع خود استفاده کنید: + +```Python hl_lines="9 14" +from typing import Optional + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Optional[str] = None): + return {"item_id": item_id, "q": q} +``` + +**توجه**: + +اگر با `async / await` آشنا نیستید، به بخش _"عجله‌ دارید?"_ در صفحه درباره `async` و `await` در مستندات مراجعه کنید. + + +
+ +### اجرا کنید + +با استفاده از دستور زیر سرور را اجرا کنید: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +
+درباره دستور uvicorn main:app --reload... + +دستور `uvicorn main:app` شامل موارد زیر است: + +* `main`: فایل `main.py` (ماژول پایتون ایجاد شده). +* `app`: شیء ایجاد شده در فایل `main.py` در خط `app = FastAPI()`. +* `--reload`: ریستارت کردن سرور با تغییر کد. تنها در هنگام توسعه از این گزینه استفاده شود.. + +
+ +### بررسی کنید + +آدرس http://127.0.0.1:8000/items/5?q=somequery را در مرورگر خود باز کنید. + +پاسخ JSON زیر را مشاهده خواهید کرد: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +تا اینجا شما APIای ساختید که: + +* درخواست‌های HTTP به _مسیرهای_ `/` و `/items/{item_id}` را دریافت می‌کند. +* هردو _مسیر_ عملیات (یا HTTP _متد_) `GET` را پشتیبانی می‌کنند. +* _مسیر_ `/items/{item_id}` شامل _پارامتر مسیر_ `item_id` از نوع `int` است. +* _مسیر_ `/items/{item_id}` شامل _پارامتر پرسمان_ اختیاری `q` از نوع `str` است. + +### مستندات API تعاملی + +حال به آدرس http://127.0.0.1:8000/docs بروید. + +مستندات API تعاملی (ایجاد شده به کمک Swagger UI) را مشاهده خواهید کرد: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### مستندات API جایگزین + +حال به آدرس http://127.0.0.1:8000/redoc بروید. + +مستندات خودکار دیگری را مشاهده خواهید کرد که به کمک ReDoc ایجاد می‌شود: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## تغییر مثال + +حال فایل `main.py` را مطابق زیر ویرایش کنید تا بتوانید بدنه یک درخواست `PUT` را دریافت کنید. + +به کمک Pydantic بدنه درخواست را با انواع استاندارد پایتون تعریف کنید. + +```Python hl_lines="4 9-12 25-27" +from typing import Optional + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Union[bool, None] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +سرور به صورت خودکار ری‌استارت می‌شود (زیرا پیشتر از گزینه `--reload` در دستور `uvicorn` استفاده کردیم). + +### تغییر مستندات API تعاملی + +مجددا به آدرس http://127.0.0.1:8000/docs بروید. + +* مستندات API تعاملی به صورت خودکار به‌روز شده است و شامل بدنه تعریف شده در مرحله قبل است: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* روی دکمه "Try it out" کلیک کنید, اکنون می‌توانید پارامترهای مورد نیاز هر API را مشخص کرده و به صورت مستقیم با آنها تعامل کنید: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* سپس روی دکمه "Execute" کلیک کنید, خواهید دید که واسط کاریری با APIهای تعریف شده ارتباط برقرار کرده، پارامترهای مورد نیاز را به آن‌ها ارسال می‌کند، سپس نتایج را دریافت کرده و در صفحه نشان می‌دهد: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### تغییر مستندات API جایگزین + +حال به آدرس http://127.0.0.1:8000/redoc بروید. + +* خواهید دید که مستندات جایگزین نیز به‌روزرسانی شده و شامل پارامتر پرسمان و بدنه تعریف شده می‌باشد: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### خلاصه + +به طور خلاصه شما **یک بار** انواع پارامترها، بدنه و غیره را به عنوان پارامترهای ورودی تابع خود تعریف می‌کنید. + + این کار را با استفاده از انواع استاندارد و مدرن موجود در پایتون انجام می‌دهید. + +نیازی به یادگیری نحو جدید یا متدها و کلاس‌های یک کتابخانه بخصوص و غیره نیست. + +تنها **پایتون +۳.۶**. + +به عنوان مثال برای یک پارامتر از نوع `int`: + +```Python +item_id: int +``` + +یا برای یک مدل پیچیده‌تر مثل `Item`: + +```Python +item: Item +``` + +...و با همین اعلان تمامی قابلیت‌های زیر در دسترس قرار می‌گیرد: + +* پشتیبانی ویرایشگر متنی شامل: + * تکمیل کد. + * بررسی انواع داده. +* اعتبارسنجی داده: + * خطاهای خودکار و مشخص در هنگام نامعتبر بودن داده + * اعتبارسنجی، حتی برای اشیاء JSON تو در تو. +* تبدیل داده ورودی: که از شبکه رسیده به انواع و داد‌ه‌ پایتونی. این داده‌ شامل: + * JSON. + * پارامترهای مسیر. + * پارامترهای پرسمان. + * کوکی‌ها. + * سرآیند‌ها (هدرها). + * فرم‌ها. + * فایل‌ها. +* تبدیل داده خروجی: تبدیل از انواع و داده‌ پایتون به داده شبکه (مانند JSON): + * تبدیل انواع داده پایتونی (`str`, `int`, `float`, `bool`, `list` و غیره). + * اشیاء `datetime`. + * اشیاء `UUID`. + * qمدل‌های پایگاه‌داده. + * و موارد بیشمار دیگر. +* دو مدل مستند API تعاملی خودکار : + * Swagger UI. + * ReDoc. + +--- + +به مثال قبلی باز می‌گردیم، در این مثال **FastAPI** موارد زیر را انجام می‌دهد: + +* اعتبارسنجی اینکه پارامتر `item_id` در مسیر درخواست‌های `GET` و `PUT` موجود است . +* اعتبارسنجی اینکه پارامتر `item_id` در درخواست‌های `GET` و `PUT` از نوع `int` است. + * اگر غیر از این موارد باشد، سرویس‌گیرنده خطای مفید و مشخصی دریافت خواهد کرد. +* بررسی وجود پارامتر پرسمان اختیاری `q` (مانند `http://127.0.0.1:8000/items/foo?q=somequery`) در درخواست‌های `GET`. + * از آنجا که پارامتر `q` با `= None` مقداردهی شده است, این پارامتر اختیاری است. + * اگر از مقدار اولیه `None` استفاده نکنیم، این پارامتر الزامی خواهد بود (همانند بدنه درخواست در درخواست `PUT`). +* برای درخواست‌های `PUT` به آدرس `/items/{item_id}`, بدنه درخواست باید از نوع JSON تعریف شده باشد: + * بررسی اینکه بدنه شامل فیلدی با نام `name` و از نوع `str` است. + * بررسی اینکه بدنه شامل فیلدی با نام `price` و از نوع `float` است. + * بررسی اینکه بدنه شامل فیلدی اختیاری با نام `is_offer` است, که در صورت وجود باید از نوع `bool` باشد. + * تمامی این موارد برای اشیاء JSON در هر عمقی قابل بررسی می‌باشد. +* تبدیل از/به JSON به صورت خودکار. +* مستندسازی همه چیز با استفاده از OpenAPI, که می‌توان از آن برای موارد زیر استفاده کرد: + * سیستم مستندات تعاملی. + * تولید خودکار کد سرویس‌گیرنده‌ در زبان‌های برنامه‌نویسی بیشمار. +* فراهم سازی ۲ مستند تعاملی مبتنی بر وب به صورت پیش‌فرض . + +--- + +موارد ذکر شده تنها پاره‌ای از ویژگی‌های بیشمار FastAPI است اما ایده‌ای کلی از طرز کار آن در اختیار قرار می‌دهد. + +خط زیر را به این صورت تغییر دهید: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +از: + +```Python + ... "item_name": item.name ... +``` + +به: + +```Python + ... "item_price": item.price ... +``` + +در حین تایپ کردن توجه کنید که چگونه ویرایش‌گر، ویژگی‌های کلاس `Item` را تشخیص داده و به تکمیل خودکار آنها کمک می‌کند: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +برای مشاهده مثال‌های کامل‌تر که شامل قابلیت‌های بیشتری از FastAPI باشد به بخش آموزش - راهنمای کاربر مراجعه کنید. + +**هشدار اسپویل**: بخش آموزش - راهنمای کاربر شامل موارد زیر است: + +* اعلان **پارامترهای** موجود در بخش‌های دیگر درخواست، شامل: **سرآیند‌ (هدر)ها**, **کوکی‌ها**, **فیلد‌های فرم** و **فایل‌ها**. +* چگونگی تنظیم **محدودیت‌های اعتبارسنجی** به عنوان مثال `maximum_length` یا `regex`. +* سیستم **Dependency Injection** قوی و کاربردی. +* امنیت و تایید هویت, شامل پشتیبانی از **OAuth2** مبتنی بر **JWT tokens** و **HTTP Basic**. +* تکنیک پیشرفته برای تعریف **مدل‌های چند سطحی JSON** (بر اساس Pydantic). +* قابلیت‌های اضافی دیگر (بر اساس Starlette) شامل: + * **وب‌سوکت** + * **GraphQL** + * تست‌های خودکار آسان مبتنی بر `requests` و `pytest` + * **CORS** + * **Cookie Sessions** + * و موارد بیشمار دیگر. + +## کارایی + +معیار (بنچمارک‌)های مستقل TechEmpower حاکی از آن است که برنامه‌های **FastAPI** که تحت Uvicorn اجرا می‌شود، یکی از سریع‌ترین فریم‌ورک‌های مبتنی بر پایتون, است که کمی ضعیف‌تر از Starlette و Uvicorn عمل می‌کند (فریم‌ورک و سروری که FastAPI بر اساس آنها ایجاد شده است) (*) + +برای درک بهتری از این موضوع به بخش بنچ‌مارک‌ها مراجعه کنید. + +## نیازمندی‌های اختیاری + +استفاده شده توسط Pydantic: + +* ujson - برای "تجزیه (parse)" سریع‌تر JSON . +* email_validator - برای اعتبارسنجی آدرس‌های ایمیل. + +استفاده شده توسط Starlette: + +* requests - در صورتی که می‌خواهید از `TestClient` استفاده کنید. +* aiofiles - در صورتی که می‌خواهید از `FileResponse` و `StaticFiles` استفاده کنید. +* jinja2 - در صورتی که بخواهید از پیکربندی پیش‌فرض برای قالب‌ها استفاده کنید. +* python-multipart - در صورتی که بخواهید با استفاده از `request.form()` از قابلیت "تجزیه (parse)" فرم استفاده کنید. +* itsdangerous - در صورتی که بخواید از `SessionMiddleware` پشتیبانی کنید. +* pyyaml - برای پشتیبانی `SchemaGenerator` در Starlet (به احتمال زیاد برای کار کردن با FastAPI به آن نیازی پیدا نمی‌کنید.). +* graphene - در صورتی که از `GraphQLApp` پشتیبانی می‌کنید. +* ujson - در صورتی که بخواهید از `UJSONResponse` استفاده کنید. + +استفاده شده توسط FastAPI / Starlette: + +* uvicorn - برای سرور اجرا کننده برنامه وب. +* orjson - در صورتی که بخواهید از `ORJSONResponse` استفاده کنید. + +می‌توان همه این موارد را با استفاده از دستور `pip install fastapi[all]`. به صورت یکجا نصب کرد. + +## لایسنس + +این پروژه مشمول قوانین و مقررات لایسنس MIT است. diff --git a/docs/fa/mkdocs.yml b/docs/fa/mkdocs.yml new file mode 100644 index 000000000..7c2fe5eab --- /dev/null +++ b/docs/fa/mkdocs.yml @@ -0,0 +1,145 @@ +site_name: FastAPI +site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production +site_url: https://fastapi.tiangolo.com/fa/ +theme: + name: material + custom_dir: overrides + palette: + - media: '(prefers-color-scheme: light)' + scheme: default + primary: teal + accent: amber + toggle: + icon: material/lightbulb + name: Switch to light mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + primary: teal + accent: amber + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + features: + - search.suggest + - search.highlight + - content.tabs.link + icon: + repo: fontawesome/brands/github-alt + logo: https://fastapi.tiangolo.com/img/icon-white.svg + favicon: https://fastapi.tiangolo.com/img/favicon.png + language: fa +repo_name: tiangolo/fastapi +repo_url: https://github.com/tiangolo/fastapi +edit_uri: '' +plugins: +- search +- markdownextradata: + data: data +nav: +- FastAPI: index.md +- Languages: + - en: / + - az: /az/ + - de: /de/ + - es: /es/ + - fa: /fa/ + - fr: /fr/ + - he: /he/ + - id: /id/ + - it: /it/ + - ja: /ja/ + - ko: /ko/ + - nl: /nl/ + - pl: /pl/ + - pt: /pt/ + - ru: /ru/ + - sq: /sq/ + - sv: /sv/ + - tr: /tr/ + - uk: /uk/ + - zh: /zh/ +markdown_extensions: +- toc: + permalink: true +- markdown.extensions.codehilite: + guess_lang: false +- mdx_include: + base_path: docs +- admonition +- codehilite +- extra +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format '' +- pymdownx.tabbed: + alternate_style: true +- attr_list +- md_in_html +extra: + analytics: + provider: google + property: UA-133183413-1 + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/tiangolo/fastapi + - icon: fontawesome/brands/discord + link: https://discord.gg/VQjSZaeJmf + - icon: fontawesome/brands/twitter + link: https://twitter.com/fastapi + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/tiangolo + - icon: fontawesome/brands/dev + link: https://dev.to/tiangolo + - icon: fontawesome/brands/medium + link: https://medium.com/@tiangolo + - icon: fontawesome/solid/globe + link: https://tiangolo.com + alternate: + - link: / + name: en - English + - link: /az/ + name: az + - link: /de/ + name: de + - link: /es/ + name: es - español + - link: /fa/ + name: fa + - link: /fr/ + name: fr - français + - link: /he/ + name: he + - link: /id/ + name: id + - link: /it/ + name: it - italiano + - link: /ja/ + name: ja - 日本語 + - link: /ko/ + name: ko - 한국어 + - link: /nl/ + name: nl + - link: /pl/ + name: pl + - link: /pt/ + name: pt - português + - link: /ru/ + name: ru - русский язык + - link: /sq/ + name: sq - shqip + - link: /sv/ + name: sv - svenska + - link: /tr/ + name: tr - Türkçe + - link: /uk/ + name: uk - українська мова + - link: /zh/ + name: zh - 汉语 +extra_css: +- https://fastapi.tiangolo.com/css/termynal.css +- https://fastapi.tiangolo.com/css/custom.css +extra_javascript: +- https://fastapi.tiangolo.com/js/termynal.js +- https://fastapi.tiangolo.com/js/custom.js diff --git a/docs/fa/overrides/.gitignore b/docs/fa/overrides/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/fr/docs/alternatives.md b/docs/fr/docs/alternatives.md index bf3e7bc3c..ee20438c3 100644 --- a/docs/fr/docs/alternatives.md +++ b/docs/fr/docs/alternatives.md @@ -133,7 +133,7 @@ permanents qui les rendent inadaptés. ### Marshmallow -L'une des principales fonctionnalités nécessaires aux systèmes API est la "sérialisation" des données, qui consiste à prendre les données du code (Python) et à les convertir en quelque chose qui peut être envoyé sur le réseau. Par exemple, convertir un objet contenant des données provenant d'une base de données en un objet JSON. Convertir des objets `datetime` en strings, etc. @@ -147,7 +147,7 @@ Sans un système de validation des données, vous devriez effectuer toutes les v Ces fonctionnalités sont ce pourquoi Marshmallow a été construit. C'est une excellente bibliothèque, et je l'ai déjà beaucoup utilisée. -Mais elle a été créée avant que les type hints n'existent en Python. Ainsi, pour définir chaque schéma, vous devez utiliser des utilitaires et des classes spécifiques fournies par Marshmallow. !!! check "A inspiré **FastAPI** à" @@ -155,7 +155,7 @@ Utilisez du code pour définir des "schémas" qui fournissent automatiquement le ### Webargs -Une autre grande fonctionnalité requise par les API est le parsing des données provenant des requêtes entrantes. Webargs est un outil qui a été créé pour fournir cela par-dessus plusieurs frameworks, dont Flask. diff --git a/docs/fr/docs/async.md b/docs/fr/docs/async.md index 20f4ee101..db88c4663 100644 --- a/docs/fr/docs/async.md +++ b/docs/fr/docs/async.md @@ -205,10 +205,6 @@ Cette "attente" 🕙 se mesure en microsecondes, mais tout de même, en cumulé C'est pourquoi il est logique d'utiliser du code asynchrone ⏸🔀⏯ pour des APIs web. -La plupart des frameworks Python existants (y compris Flask et Django) ont été créés avant que les nouvelles fonctionnalités asynchrones de Python n'existent. Donc, les façons dont ils peuvent être déployés supportent l'exécution parallèle et une ancienne forme d'exécution asynchrone qui n'est pas aussi puissante que les nouvelles fonctionnalités de Python. - -Et cela, bien que les spécifications principales du web asynchrone en Python (ou ASGI) ont été développées chez Django, pour ajouter le support des WebSockets. - Ce type d'asynchronicité est ce qui a rendu NodeJS populaire (bien que NodeJS ne soit pas parallèle) et c'est la force du Go en tant que langage de programmation. Et c'est le même niveau de performance que celui obtenu avec **FastAPI**. @@ -220,7 +216,7 @@ Et comme on peut avoir du parallélisme et de l'asynchronicité en même temps, Nope ! C'est ça la morale de l'histoire. La concurrence est différente du parallélisme. C'est mieux sur des scénarios **spécifiques** qui impliquent beaucoup d'attente. À cause de ça, c'est généralement bien meilleur que le parallélisme pour le développement d'applications web. Mais pas pour tout. - + Donc pour équilibrer tout ça, imaginez l'histoire suivante : > Vous devez nettoyer une grande et sale maison. @@ -293,7 +289,7 @@ def get_sequential_burgers(number: int): Avec `async def`, Python sait que dans cette fonction il doit prendre en compte les expressions `await`, et qu'il peut mettre en pause ⏸ l'exécution de la fonction pour aller faire autre chose 🔀 avant de revenir. -Pour appeler une fonction définie avec `async def`, vous devez utiliser `await`. Donc ceci ne marche pas : +Pour appeler une fonction définie avec `async def`, vous devez utiliser `await`. Donc ceci ne marche pas : ```Python # Ceci ne fonctionne pas, car get_burgers a été défini avec async def @@ -375,7 +371,7 @@ Au final, dans les deux situations, il est fort probable que **FastAPI** soit to La même chose s'applique aux dépendances. Si une dépendance est définie avec `def` plutôt que `async def`, elle est exécutée dans la threadpool externe. -### Sous-dépendances +### Sous-dépendances Vous pouvez avoir de multiples dépendances et sous-dépendances dépendant les unes des autres (en tant que paramètres de la définition de la *fonction de chemin*), certaines créées avec `async def` et d'autres avec `def`. Cela fonctionnerait aussi, et celles définies avec un simple `def` seraient exécutées sur un thread externe (venant de la threadpool) plutôt que d'être "attendues". diff --git a/docs/fr/docs/deployment/docker.md b/docs/fr/docs/deployment/docker.md index e4b59afbf..d2dcae722 100644 --- a/docs/fr/docs/deployment/docker.md +++ b/docs/fr/docs/deployment/docker.md @@ -118,7 +118,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage
-Vous disposez maintenant d'un serveur FastAPI optimisé dans un conteneur Docker. Configuré automatiquement pour votre +Vous disposez maintenant d'un serveur FastAPI optimisé dans un conteneur Docker. Configuré automatiquement pour votre serveur actuel (et le nombre de cœurs du CPU). ## Vérifier @@ -139,7 +139,7 @@ Vous verrez la documentation interactive automatique de l'API (fournie par http://192.168.99.100/redoc ou http://127.0.0.1/redoc (ou équivalent, en utilisant votre hôte Docker). @@ -149,7 +149,7 @@ Vous verrez la documentation automatique alternative (fournie par Traefik est un reverse proxy/load balancer +Traefik est un reverse proxy/load balancer haute performance. Il peut faire office de "Proxy de terminaison TLS" (entre autres fonctionnalités). Il est intégré à Let's Encrypt. Ainsi, il peut gérer toutes les parties HTTPS, y compris l'acquisition et le renouvellement des certificats. @@ -164,7 +164,7 @@ Avec ces informations et ces outils, passez à la section suivante pour tout com Vous pouvez avoir un cluster en mode Docker Swarm configuré en quelques minutes (environ 20 min) avec un processus Traefik principal gérant HTTPS (y compris l'acquisition et le renouvellement des certificats). -En utilisant le mode Docker Swarm, vous pouvez commencer par un "cluster" d'une seule machine (il peut même s'agir +En utilisant le mode Docker Swarm, vous pouvez commencer par un "cluster" d'une seule machine (il peut même s'agir d'un serveur à 5 USD/mois) et ensuite vous pouvez vous développer autant que vous le souhaitez en ajoutant d'autres serveurs. Pour configurer un cluster en mode Docker Swarm avec Traefik et la gestion de HTTPS, suivez ce guide : diff --git a/docs/fr/docs/deployment/index.md b/docs/fr/docs/deployment/index.md new file mode 100644 index 000000000..e855adfa3 --- /dev/null +++ b/docs/fr/docs/deployment/index.md @@ -0,0 +1,28 @@ +# Déploiement - Intro + +Le déploiement d'une application **FastAPI** est relativement simple. + +## Que signifie le déploiement + +**Déployer** une application signifie effectuer les étapes nécessaires pour la rendre **disponible pour les +utilisateurs**. + +Pour une **API Web**, cela implique normalement de la placer sur une **machine distante**, avec un **programme serveur** +qui offre de bonnes performances, une bonne stabilité, _etc._, afin que vos **utilisateurs** puissent **accéder** à +l'application efficacement et sans interruption ni problème. + +Ceci contraste avec les étapes de **développement**, où vous êtes constamment en train de modifier le code, de le casser +et de le réparer, d'arrêter et de redémarrer le serveur de développement, _etc._ + +## Stratégies de déploiement + +Il existe plusieurs façons de procéder, en fonction de votre cas d'utilisation spécifique et des outils que vous +utilisez. + +Vous pouvez **déployer un serveur** vous-même en utilisant une combinaison d'outils, vous pouvez utiliser un **service +cloud** qui fait une partie du travail pour vous, ou encore d'autres options possibles. + +Je vais vous montrer certains des principaux concepts que vous devriez probablement avoir à l'esprit lors du déploiement +d'une application **FastAPI** (bien que la plupart de ces concepts s'appliquent à tout autre type d'application web). + +Vous verrez plus de détails à avoir en tête et certaines des techniques pour le faire dans les sections suivantes. ✨ diff --git a/docs/fr/docs/fastapi-people.md b/docs/fr/docs/fastapi-people.md index 9ec2718c4..945f0794e 100644 --- a/docs/fr/docs/fastapi-people.md +++ b/docs/fr/docs/fastapi-people.md @@ -114,6 +114,8 @@ Ce sont les **Sponsors**. 😎 Ils soutiennent mon travail avec **FastAPI** (et d'autres) avec GitHub Sponsors. +{% if sponsors %} + {% if sponsors.gold %} ### Gold Sponsors @@ -141,6 +143,7 @@ Ils soutiennent mon travail avec **FastAPI** (et d'autres) avec IDE/linter/cerveau**: * Parce que les structures de données de pydantic consistent seulement en une instance de classe que vous définissez; l'auto-complétion, le linting, mypy et votre intuition devrait être largement suffisante pour valider vos données. * **Rapide**: - * Dans les benchmarks Pydantic est plus rapide que toutes les autres librairies testées. + * Dans les benchmarks Pydantic est plus rapide que toutes les autres librairies testées. * Valide les **structures complexes**: * Utilise les modèles hiérarchique de Pydantic, le `typage` Python pour les `Lists`, `Dict`, etc. * Et les validateurs permettent aux schémas de données complexes d'être clairement et facilement définis, validés et documentés sous forme d'un schéma JSON. diff --git a/docs/fr/docs/history-design-future.md b/docs/fr/docs/history-design-future.md new file mode 100644 index 000000000..b77664be6 --- /dev/null +++ b/docs/fr/docs/history-design-future.md @@ -0,0 +1,79 @@ +# Histoire, conception et avenir + +Il y a quelque temps, un utilisateur de **FastAPI** a demandé : + +> Quelle est l'histoire de ce projet ? Il semble être sorti de nulle part et est devenu génial en quelques semaines [...]. + +Voici un petit bout de cette histoire. + +## Alternatives + +Je crée des API avec des exigences complexes depuis plusieurs années (Machine Learning, systèmes distribués, jobs asynchrones, bases de données NoSQL, etc), en dirigeant plusieurs équipes de développeurs. + +Dans ce cadre, j'ai dû étudier, tester et utiliser de nombreuses alternatives. + +L'histoire de **FastAPI** est en grande partie l'histoire de ses prédécesseurs. + +Comme dit dans la section [Alternatives](alternatives.md){.internal-link target=\_blank} : + +
+ +**FastAPI** n'existerait pas sans le travail antérieur d'autres personnes. + +Il y a eu de nombreux outils créés auparavant qui ont contribué à inspirer sa création. + +J'ai évité la création d'un nouveau framework pendant plusieurs années. J'ai d'abord essayé de résoudre toutes les fonctionnalités couvertes par **FastAPI** en utilisant de nombreux frameworks, plug-ins et outils différents. + +Mais à un moment donné, il n'y avait pas d'autre option que de créer quelque chose qui offre toutes ces fonctionnalités, en prenant les meilleures idées des outils précédents, et en les combinant de la meilleure façon possible, en utilisant des fonctionnalités du langage qui n'étaient même pas disponibles auparavant (annotations de type pour Python 3.6+). + +
+ +## Recherche + +En utilisant toutes les alternatives précédentes, j'ai eu la chance d'apprendre de toutes, de prendre des idées, et de les combiner de la meilleure façon que j'ai pu trouver pour moi-même et les équipes de développeurs avec lesquelles j'ai travaillé. + +Par exemple, il était clair que l'idéal était de se baser sur les annotations de type Python standard. + +De plus, la meilleure approche était d'utiliser des normes déjà existantes. + +Ainsi, avant même de commencer à coder **FastAPI**, j'ai passé plusieurs mois à étudier les spécifications d'OpenAPI, JSON Schema, OAuth2, etc. Comprendre leurs relations, leurs similarités et leurs différences. + +## Conception + +Ensuite, j'ai passé du temps à concevoir l'"API" de développeur que je voulais avoir en tant qu'utilisateur (en tant que développeur utilisant FastAPI). + +J'ai testé plusieurs idées dans les éditeurs Python les plus populaires : PyCharm, VS Code, les éditeurs basés sur Jedi. + +D'après la dernière Enquête Développeurs Python, cela couvre environ 80% des utilisateurs. + +Cela signifie que **FastAPI** a été spécifiquement testé avec les éditeurs utilisés par 80% des développeurs Python. Et comme la plupart des autres éditeurs ont tendance à fonctionner de façon similaire, tous ses avantages devraient fonctionner pour pratiquement tous les éditeurs. + +Ainsi, j'ai pu trouver les meilleurs moyens de réduire autant que possible la duplication du code, d'avoir la complétion partout, les contrôles de type et d'erreur, etc. + +Le tout de manière à offrir la meilleure expérience de développement à tous les développeurs. + +## Exigences + +Après avoir testé plusieurs alternatives, j'ai décidé que j'allais utiliser **Pydantic** pour ses avantages. + +J'y ai ensuite contribué, pour le rendre entièrement compatible avec JSON Schema, pour supporter différentes manières de définir les déclarations de contraintes, et pour améliorer le support des éditeurs (vérifications de type, autocomplétion) sur la base des tests effectués dans plusieurs éditeurs. + +Pendant le développement, j'ai également contribué à **Starlette**, l'autre exigence clé. + +## Développement + +Au moment où j'ai commencé à créer **FastAPI** lui-même, la plupart des pièces étaient déjà en place, la conception était définie, les exigences et les outils étaient prêts, et la connaissance des normes et des spécifications était claire et fraîche. + +## Futur + +À ce stade, il est déjà clair que **FastAPI** et ses idées sont utiles pour de nombreuses personnes. + +Elle a été préférée aux solutions précédentes parce qu'elle convient mieux à de nombreux cas d'utilisation. + +De nombreux développeurs et équipes dépendent déjà de **FastAPI** pour leurs projets (y compris moi et mon équipe). + +Mais il y a encore de nombreuses améliorations et fonctionnalités à venir. + +**FastAPI** a un grand avenir devant lui. + +Et [votre aide](help-fastapi.md){.internal-link target=\_blank} est grandement appréciée. diff --git a/docs/fr/docs/index.md b/docs/fr/docs/index.md index 40e6dfdff..1307c063b 100644 --- a/docs/fr/docs/index.md +++ b/docs/fr/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -149,7 +149,7 @@ $ pip install uvicorn[standard] * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,7 +162,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,7 +185,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -264,7 +264,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 10 11 12 25 26 27" -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +275,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +284,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. @@ -464,4 +463,4 @@ You can install all of these with `pip install fastapi[all]`. ## License -This project is licensed under the terms of the MIT license. \ No newline at end of file +This project is licensed under the terms of the MIT license. diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md index 06ef93cd7..f7cf1a6cc 100644 --- a/docs/fr/docs/tutorial/background-tasks.md +++ b/docs/fr/docs/tutorial/background-tasks.md @@ -9,7 +9,7 @@ Cela comprend, par exemple : * Les notifications par email envoyées après l'exécution d'une action : * Étant donné que se connecter à un serveur et envoyer un email a tendance à être «lent» (plusieurs secondes), vous pouvez retourner la réponse directement et envoyer la notification en arrière-plan. * Traiter des données : - * Par exemple, si vous recevez un fichier qui doit passer par un traitement lent, vous pouvez retourner une réponse «Accepted» (HTTP 202) puis faire le traitement en arrière-plan. + * Par exemple, si vous recevez un fichier qui doit passer par un traitement lent, vous pouvez retourner une réponse «Accepted» (HTTP 202) puis faire le traitement en arrière-plan. ## Utiliser `BackgroundTasks` @@ -73,7 +73,7 @@ La classe `BackgroundTasks` provient directement de Celery. +Si vous avez besoin de réaliser des traitements lourds en tâche d'arrière-plan et que vous n'avez pas besoin que ces traitements aient lieu dans le même process (par exemple, pas besoin de partager la mémoire, les variables, etc.), il peut s'avérer profitable d'utiliser des outils plus importants tels que Celery. Ces outils nécessitent généralement des configurations plus complexes ainsi qu'un gestionnaire de queue de message, comme RabbitMQ ou Redis, mais ils permettent d'exécuter des tâches d'arrière-plan dans différents process, et potentiellement, sur plusieurs serveurs. diff --git a/docs/fr/docs/tutorial/body.md b/docs/fr/docs/tutorial/body.md index c0953f49f..1e732d336 100644 --- a/docs/fr/docs/tutorial/body.md +++ b/docs/fr/docs/tutorial/body.md @@ -111,7 +111,7 @@ Mais vous auriez le même support de l'éditeur avec !!! tip "Astuce" - Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le Plugin PyCharm. + Si vous utilisez PyCharm comme éditeur, vous pouvez utiliser le Plugin Pydantic PyCharm Plugin. Ce qui améliore le support pour les modèles Pydantic avec : @@ -162,4 +162,4 @@ Les paramètres de la fonction seront reconnus comme tel : ## Sans Pydantic -Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md){.internal-link target=_blank}. \ No newline at end of file +Si vous ne voulez pas utiliser des modèles Pydantic, vous pouvez aussi utiliser des paramètres de **Corps**. Pour cela, allez voir la partie de la documentation sur [Corps de la requête - Paramètres multiples](body-multiple-params.md){.internal-link target=_blank}. diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md index 3a81362f6..224c340c6 100644 --- a/docs/fr/docs/tutorial/first-steps.md +++ b/docs/fr/docs/tutorial/first-steps.md @@ -280,7 +280,7 @@ Tout comme celles les plus exotiques : **FastAPI** n'impose pas de sens spécifique à chacune d'elle. - Les informations qui sont présentées ici forment une directive générale, pas des obligations. + Les informations qui sont présentées ici forment une directive générale, pas des obligations. Par exemple, quand l'on utilise **GraphQL**, toutes les actions sont effectuées en utilisant uniquement des opérations `POST`. diff --git a/docs/fr/docs/tutorial/path-params.md b/docs/fr/docs/tutorial/path-params.md index 58f53e008..894d62dd4 100644 --- a/docs/fr/docs/tutorial/path-params.md +++ b/docs/fr/docs/tutorial/path-params.md @@ -8,7 +8,7 @@ Vous pouvez déclarer des "paramètres" ou "variables" de chemin avec la même s {!../../../docs_src/path_params/tutorial001.py!} ``` -La valeur du paramètre `item_id` sera transmise à la fonction dans l'argument `item_id`. +La valeur du paramètre `item_id` sera transmise à la fonction dans l'argument `item_id`. Donc, si vous exécutez cet exemple et allez sur http://127.0.0.1:8000/items/foo, vous verrez comme réponse : @@ -44,7 +44,7 @@ Si vous exécutez cet exemple et allez sur "parsing" automatique. ## Validation de données @@ -91,7 +91,7 @@ documentation générée automatiquement et interactive : On voit bien dans la documentation que `item_id` est déclaré comme entier. -## Les avantages d'avoir une documentation basée sur une norme, et la documentation alternative. +## Les avantages d'avoir une documentation basée sur une norme, et la documentation alternative. Le schéma généré suivant la norme OpenAPI, il existe de nombreux outils compatibles. @@ -102,7 +102,7 @@ sur De la même façon, il existe bien d'autres outils compatibles, y compris des outils de génération de code -pour de nombreux langages. +pour de nombreux langages. ## Pydantic diff --git a/docs/fr/docs/tutorial/query-params.md b/docs/fr/docs/tutorial/query-params.md index f1f2a605d..7bf3b9e79 100644 --- a/docs/fr/docs/tutorial/query-params.md +++ b/docs/fr/docs/tutorial/query-params.md @@ -6,7 +6,7 @@ Quand vous déclarez des paramètres dans votre fonction de chemin qui ne font p {!../../../docs_src/query_params/tutorial001.py!} ``` -La partie appelée requête (ou **query**) dans une URL est l'ensemble des paires clés-valeurs placées après le `?` , séparées par des `&`. +La partie appelée requête (ou **query**) dans une URL est l'ensemble des paires clés-valeurs placées après le `?` , séparées par des `&`. Par exemple, dans l'URL : @@ -120,7 +120,7 @@ ou n'importe quelle autre variation de casse (tout en majuscules, uniquement la ## Multiples paramètres de chemin et de requête -Vous pouvez déclarer plusieurs paramètres de chemin et paramètres de requête dans la même fonction, **FastAPI** saura comment les gérer. +Vous pouvez déclarer plusieurs paramètres de chemin et paramètres de requête dans la même fonction, **FastAPI** saura comment les gérer. Et vous n'avez pas besoin de les déclarer dans un ordre spécifique. diff --git a/docs/fr/mkdocs.yml b/docs/fr/mkdocs.yml index ff16e1d78..6bed7be73 100644 --- a/docs/fr/mkdocs.yml +++ b/docs/fr/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -63,9 +69,11 @@ nav: - tutorial/background-tasks.md - async.md - Déploiement: + - deployment/index.md - deployment/docker.md - project-generation.md - alternatives.md +- history-design-future.md - external-links.md markdown_extensions: - toc: @@ -84,6 +92,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -112,8 +122,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -122,6 +136,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -130,6 +146,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/he/docs/index.md b/docs/he/docs/index.md new file mode 100644 index 000000000..fa63d8cb7 --- /dev/null +++ b/docs/he/docs/index.md @@ -0,0 +1,464 @@ +

+ FastAPI +

+

+ תשתית FastAPI, ביצועים גבוהים, קלה ללמידה, מהירה לתכנות, מוכנה לסביבת ייצור +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**תיעוד**: https://fastapi.tiangolo.com + +**קוד**: https://github.com/tiangolo/fastapi + +--- + +FastAPI היא תשתית רשת מודרנית ומהירה (ביצועים גבוהים) לבניית ממשקי תכנות יישומים (API) עם פייתון 3.6+ בהתבסס על רמזי טיפוסים סטנדרטיים. + +תכונות המפתח הן: + +- **מהירה**: ביצועים גבוהים מאוד, בקנה אחד עם NodeJS ו - Go (תודות ל - Starlette ו - Pydantic). [אחת מתשתיות הפייתון המהירות ביותר](#performance). + +- **מהירה לתכנות**: הגבירו את מהירות פיתוח התכונות החדשות בכ - %200 עד %300. \* +- **פחות שגיאות**: מנעו כ - %40 משגיאות אנוש (מפתחים). \* +- **אינטואיטיבית**: תמיכת עורך מעולה. השלמה בכל מקום. פחות זמן ניפוי שגיאות. +- **קלה**: מתוכננת להיות קלה לשימוש וללמידה. פחות זמן קריאת תיעוד. +- **קצרה**: מזערו שכפול קוד. מספר תכונות מכל הכרזת פרמטר. פחות שגיאות. +- **חסונה**: קבלו קוד מוכן לסביבת ייצור. עם תיעוד אינטרקטיבי אוטומטי. +- **מבוססת סטנדרטים**: מבוססת על (ותואמת לחלוטין ל -) הסטדנרטים הפתוחים לממשקי תכנות יישומים: OpenAPI (ידועים לשעבר כ - Swagger) ו - JSON Schema. + +\* הערכה מבוססת על בדיקות של צוות פיתוח פנימי שבונה אפליקציות בסביבת ייצור. + +## נותני חסות + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +נותני חסות אחרים + +## דעות + +"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" + +
Kabir Khan - Microsoft (ref)
+ +--- + +"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" + +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +"_I’m over the moon excited about **FastAPI**. It’s so fun!_" + +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" + +
Timothy Crosley - Hug creator (ref)
+ +--- + +"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" + +"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, ה - FastAPI של ממשקי שורת פקודה (CLI). + + + +אם אתם בונים אפליקציית CLI לשימוש במסוף במקום ממשק רשת, העיפו מבט על **Typer**. + +**Typer** היא אחותה הקטנה של FastAPI. ומטרתה היא להיות ה - **FastAPI של ממשקי שורת פקודה**. ⌨️ 🚀 + +## תלויות + +פייתון 3.6+ + +FastAPI עומדת על כתפי ענקיות: + +- Starlette לחלקי הרשת. +- Pydantic לחלקי המידע. + +## התקנה + +
+ +```console +$ pip install fastapi + +---> 100% +``` + +
+ +תצטרכו גם שרת ASGI כגון Uvicorn או Hypercorn. + +
+ +```console +$ pip install "uvicorn[standard]" + +---> 100% +``` + +
+ +## דוגמא + +### צרו אותה + +- צרו קובץ בשם `main.py` עם: + +```Python +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+או השתמשו ב - async def... + +אם הקוד שלכם משתמש ב - `async` / `await`, השתמשו ב - `async def`: + +```Python hl_lines="9 14" +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +**שימו לב**: + +אם אינכם יודעים, בדקו את פרק "ממהרים?" על `async` ו - `await` בתיעוד. + +
+ +### הריצו אותה + +התחילו את השרת עם: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +
+על הפקודה uvicorn main:app --reload... + +הפקודה `uvicorn main:app` מתייחסת ל: + +- `main`: הקובץ `main.py` (מודול פייתון). +- `app`: האובייקט שנוצר בתוך `main.py` עם השורה app = FastAPI(). +- --reload: גרמו לשרת להתאתחל לאחר שינויים בקוד. עשו זאת רק בסביבת פיתוח. + +
+ +### בדקו אותה + +פתחו את הדפדפן שלכם בכתובת http://127.0.0.1:8000/items/5?q=somequery. + +אתם תראו תגובת JSON: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +כבר יצרתם API ש: + +- מקבל בקשות HTTP בנתיבים `/` ו - /items/{item_id}. +- שני ה _נתיבים_ מקבלים _בקשות_ `GET` (ידועות גם כ*מתודות* HTTP). +- ה _נתיב_ /items/{item_id} כולל \*פרמטר נתיב\_ `item_id` שאמור להיות `int`. +- ה _נתיב_ /items/{item_id} \*פרמטר שאילתא\_ אופציונלי `q`. + +### תיעוד API אינטרקטיבי + +כעת פנו לכתובת http://127.0.0.1:8000/docs. + +אתם תראו את התיעוד האוטומטי (מסופק על ידי Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### תיעוד אלטרנטיבי + +כעת פנו לכתובת http://127.0.0.1:8000/redoc. + +אתם תראו תיעוד אלטרנטיבי (מסופק על ידי ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## שדרוג לדוגמא + +כעת ערכו את הקובץ `main.py` כך שיוכל לקבל גוף מבקשת `PUT`. + +הגדירו את הגוף בעזרת רמזי טיפוסים סטנדרטיים, הודות ל - `Pydantic`. + +```Python hl_lines="4 9-12 25-27" +from typing import Union + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Union[bool, None] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +השרת אמול להתאתחל אוטומטית (מאחר והוספתם --reload לפקודת `uvicorn` שלמעלה). + +### שדרוג התיעוד האינטרקטיבי + +כעת פנו לכתובת http://127.0.0.1:8000/docs. + +- התיעוד האוטומטי יתעדכן, כולל הגוף החדש: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +- לחצו על הכפתור "Try it out", הוא יאפשר לכם למלא את הפרמטרים ולעבוד ישירות מול ה - API. + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +- אחר כך לחצו על הכפתור "Execute", האתר יתקשר עם ה - API שלכם, ישלח את הפרמטרים, ישיג את התוצאות ואז יראה אותן על המסך: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### שדרוג התיעוד האלטרנטיבי + +כעת פנו לכתובת http://127.0.0.1:8000/redoc. + +- התיעוד האלטרנטיבי גם יראה את פרמטר השאילתא והגוף החדשים. + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### סיכום + +לסיכום, אתם מכריזים ** פעם אחת** על טיפוסי הפרמטרים, גוף וכו' כפרמטרים לפונקציה. + +אתם עושים את זה עם טיפוסי פייתון מודרניים. + +אתם לא צריכים ללמוד תחביר חדש, מתודות או מחלקות של ספרייה ספיציפית, וכו' + +רק **פייתון 3.6+** סטנדרטי. + +לדוגמא, ל - `int`: + +```Python +item_id: int +``` + +או למודל `Item` מורכב יותר: + +```Python +item: Item +``` + +...ועם הכרזת הטיפוס האחת הזו אתם מקבלים: + +- תמיכת עורך, כולל: + - השלמות. + - בדיקת טיפוסים. +- אימות מידע: + - שגיאות ברורות ואטומטיות כאשר מוכנס מידע לא חוקי . + - אימות אפילו לאובייקטי JSON מקוננים. +- המרה של מידע קלט: המרה של מידע שמגיע מהרשת למידע וטיפוסים של פייתון. קורא מ: + - JSON. + - פרמטרי נתיב. + - פרמטרי שאילתא. + - עוגיות. + - כותרות. + - טפסים. + - קבצים. +- המרה של מידע פלט: המרה של מידע וטיפוסים מפייתון למידע רשת (כ - JSON): + - המירו טיפוסי פייתון (`str`, `int`, `float`, `bool`, `list`, etc). + - עצמי `datetime`. + - עצמי `UUID`. + - מודלי בסיסי נתונים. + - ...ורבים אחרים. +- תיעוד API אוטומטי ואינטרקטיבית כולל שתי אלטרנטיבות לממשק המשתמש: + - Swagger UI. + - ReDoc. + +--- + +בחזרה לדוגמאת הקוד הקודמת, **FastAPI** ידאג: + +- לאמת שיש `item_id` בנתיב בבקשות `GET` ו - `PUT`. +- לאמת שה - `item_id` הוא מטיפוס `int` בבקשות `GET` ו - `PUT`. + - אם הוא לא, הלקוח יראה שגיאה ברורה ושימושית. +- לבדוק האם קיים פרמטר שאילתא בשם `q` (קרי `http://127.0.0.1:8000/items/foo?q=somequery`) לבקשות `GET`. + - מאחר והפרמטר `q` מוגדר עם = None, הוא אופציונלי. + - לולא ה - `None` הוא היה חובה (כמו הגוף במקרה של `PUT`). +- לבקשות `PUT` לנתיב /items/{item_id}, לקרוא את גוף הבקשה כ - JSON: + - לאמת שהוא כולל את מאפיין החובה `name` שאמור להיות מטיפוס `str`. + - לאמת שהוא כולל את מאפיין החובה `price` שחייב להיות מטיפוס `float`. + - לבדוק האם הוא כולל את מאפיין הרשות `is_offer` שאמור להיות מטיפוס `bool`, אם הוא נמצא. + - כל זה יעבוד גם לאובייקט JSON מקונן. +- להמיר מ - JSON ול- JSON אוטומטית. +- לתעד הכל באמצעות OpenAPI, תיעוד שבו יוכלו להשתמש: + - מערכות תיעוד אינטרקטיביות. + - מערכות ייצור קוד אוטומטיות, להרבה שפות. +- לספק ישירות שתי מערכות תיעוד רשתיות. + +--- + +רק גרדנו את קצה הקרחון, אבל כבר יש לכם רעיון של איך הכל עובד. + +נסו לשנות את השורה: + +```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) + +לדוגמא יותר שלמה שכוללת עוד תכונות, ראו את המדריך - למשתמש. + +**התראת ספוילרים**: המדריך - למשתמש כולל: + +- הכרזה על **פרמטרים** ממקורות אחרים ושונים כגון: **כותרות**, **עוגיות**, **טפסים** ו - **קבצים**. +- איך לקבוע **מגבלות אימות** בעזרת `maximum_length` או `regex`. +- דרך חזקה וקלה להשתמש ב**הזרקת תלויות**. +- אבטחה והתאמתות, כולל תמיכה ב - **OAuth2** עם **JWT** והתאמתות **HTTP Basic**. +- טכניקות מתקדמות (אבל קלות באותה מידה) להכרזת אובייקטי JSON מקוננים (תודות ל - Pydantic). +- אינטרקציה עם **GraphQL** דרך Strawberry וספריות אחרות. +- תכונות נוספות רבות (תודות ל - Starlette) כגון: + - **WebSockets** + - בדיקות קלות במיוחד מבוססות על `requests` ו - `pytest` + - **CORS** + - **Cookie Sessions** + - ...ועוד. + +## ביצועים + +בדיקות עצמאיות של TechEmpower הראו שאפליקציות **FastAPI** שרצות תחת Uvicorn הן מתשתיות הפייתון המהירות ביותר, רק מתחת ל - Starlette ו - Uvicorn עצמן (ש - FastAPI מבוססת עליהן). (\*) + +כדי להבין עוד על הנושא, ראו את הפרק Benchmarks. + +## תלויות אופציונליות + +בשימוש Pydantic: + +- ujson - "פרסור" JSON. +- email_validator - לאימות כתובות אימייל. + +בשימוש Starlette: + +- requests - דרוש אם ברצונכם להשתמש ב - `TestClient`. +- jinja2 - דרוש אם ברצונכם להשתמש בברירת המחדל של תצורת הטמפלייטים. +- python-multipart - דרוש אם ברצונכם לתמוך ב "פרסור" טפסים, באצמעות request.form(). +- itsdangerous - דרוש אם ברצונכם להשתמש ב - `SessionMiddleware`. +- pyyaml - דרוש אם ברצונכם להשתמש ב - `SchemaGenerator` של Starlette (כנראה שאתם לא צריכים את זה עם FastAPI). +- ujson - דרוש אם ברצונכם להשתמש ב - `UJSONResponse`. + +בשימוש FastAPI / Starlette: + +- uvicorn - לשרת שטוען ומגיש את האפליקציה שלכם. +- orjson - דרוש אם ברצונכם להשתמש ב - `ORJSONResponse`. + +תוכלו להתקין את כל אלו באמצעות pip install "fastapi[all]". + +## רשיון + +הפרויקט הזה הוא תחת התנאים של רשיון MIT. diff --git a/docs/he/mkdocs.yml b/docs/he/mkdocs.yml new file mode 100644 index 000000000..3279099b5 --- /dev/null +++ b/docs/he/mkdocs.yml @@ -0,0 +1,145 @@ +site_name: FastAPI +site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production +site_url: https://fastapi.tiangolo.com/he/ +theme: + name: material + custom_dir: overrides + palette: + - media: '(prefers-color-scheme: light)' + scheme: default + primary: teal + accent: amber + toggle: + icon: material/lightbulb + name: Switch to light mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + primary: teal + accent: amber + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + features: + - search.suggest + - search.highlight + - content.tabs.link + icon: + repo: fontawesome/brands/github-alt + logo: https://fastapi.tiangolo.com/img/icon-white.svg + favicon: https://fastapi.tiangolo.com/img/favicon.png + language: he +repo_name: tiangolo/fastapi +repo_url: https://github.com/tiangolo/fastapi +edit_uri: '' +plugins: +- search +- markdownextradata: + data: data +nav: +- FastAPI: index.md +- Languages: + - en: / + - az: /az/ + - de: /de/ + - es: /es/ + - fa: /fa/ + - fr: /fr/ + - he: /he/ + - id: /id/ + - it: /it/ + - ja: /ja/ + - ko: /ko/ + - nl: /nl/ + - pl: /pl/ + - pt: /pt/ + - ru: /ru/ + - sq: /sq/ + - sv: /sv/ + - tr: /tr/ + - uk: /uk/ + - zh: /zh/ +markdown_extensions: +- toc: + permalink: true +- markdown.extensions.codehilite: + guess_lang: false +- mdx_include: + base_path: docs +- admonition +- codehilite +- extra +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format '' +- pymdownx.tabbed: + alternate_style: true +- attr_list +- md_in_html +extra: + analytics: + provider: google + property: UA-133183413-1 + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/tiangolo/fastapi + - icon: fontawesome/brands/discord + link: https://discord.gg/VQjSZaeJmf + - icon: fontawesome/brands/twitter + link: https://twitter.com/fastapi + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/tiangolo + - icon: fontawesome/brands/dev + link: https://dev.to/tiangolo + - icon: fontawesome/brands/medium + link: https://medium.com/@tiangolo + - icon: fontawesome/solid/globe + link: https://tiangolo.com + alternate: + - link: / + name: en - English + - link: /az/ + name: az + - link: /de/ + name: de + - link: /es/ + name: es - español + - link: /fa/ + name: fa + - link: /fr/ + name: fr - français + - link: /he/ + name: he + - link: /id/ + name: id + - link: /it/ + name: it - italiano + - link: /ja/ + name: ja - 日本語 + - link: /ko/ + name: ko - 한국어 + - link: /nl/ + name: nl + - link: /pl/ + name: pl + - link: /pt/ + name: pt - português + - link: /ru/ + name: ru - русский язык + - link: /sq/ + name: sq - shqip + - link: /sv/ + name: sv - svenska + - link: /tr/ + name: tr - Türkçe + - link: /uk/ + name: uk - українська мова + - link: /zh/ + name: zh - 汉语 +extra_css: +- https://fastapi.tiangolo.com/css/termynal.css +- https://fastapi.tiangolo.com/css/custom.css +extra_javascript: +- https://fastapi.tiangolo.com/js/termynal.js +- https://fastapi.tiangolo.com/js/custom.js diff --git a/docs/he/overrides/.gitignore b/docs/he/overrides/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/id/docs/index.md b/docs/id/docs/index.md index 95fb7ae21..041e0b754 100644 --- a/docs/id/docs/index.md +++ b/docs/id/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. diff --git a/docs/id/docs/tutorial/index.md b/docs/id/docs/tutorial/index.md new file mode 100644 index 000000000..8fec3c087 --- /dev/null +++ b/docs/id/docs/tutorial/index.md @@ -0,0 +1,80 @@ +# Tutorial - Pedoman Pengguna - Pengenalan + +Tutorial ini menunjukan cara menggunakan ***FastAPI*** dengan semua fitur-fiturnya, tahap demi tahap. + +Setiap bagian dibangun secara bertahap dari bagian sebelumnya, tetapi terstruktur untuk memisahkan banyak topik, sehingga kamu bisa secara langsung menuju ke topik spesifik untuk menyelesaikan kebutuhan API tertentu. + +Ini juga dibangun untuk digunakan sebagai referensi yang akan datang. + +Sehingga kamu dapat kembali lagi dan mencari apa yang kamu butuhkan dengan tepat. + +## Jalankan kode + +Semua blok-blok kode dapat dicopy dan digunakan langsung (Mereka semua sebenarnya adalah file python yang sudah teruji). + +Untuk menjalankan setiap contoh, copy kode ke file `main.py`, dan jalankan `uvicorn` dengan: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +**SANGAT disarankan** agar kamu menulis atau meng-copy kode, meng-editnya dan menjalankannya secara lokal. + +Dengan menggunakannya di dalam editor, benar-benar memperlihatkan manfaat dari FastAPI, melihat bagaimana sedikitnya kode yang harus kamu tulis, semua pengecekan tipe, pelengkapan otomatis, dll. + +--- + +## Install FastAPI + +Langkah pertama adalah dengan meng-install FastAPI. + +Untuk tutorial, kamu mungkin hendak meng-instalnya dengan semua pilihan fitur dan dependensinya: + +
+ +```console +$ pip install "fastapi[all]" + +---> 100% +``` + +
+ +...yang juga termasuk `uvicorn`, yang dapat kamu gunakan sebagai server yang menjalankan kodemu. + +!!! catatan + Kamu juga dapat meng-instalnya bagian demi bagian. + + Hal ini mungkin yang akan kamu lakukan ketika kamu hendak men-deploy aplikasimu ke tahap produksi: + + ``` + pip install fastapi + ``` + + Juga install `uvicorn` untk menjalankan server" + + ``` + pip install "uvicorn[standard]" + ``` + + Dan demikian juga untuk pilihan dependensi yang hendak kamu gunakan. + +## Pedoman Pengguna Lanjutan + +Tersedia juga **Pedoman Pengguna Lanjutan** yang dapat kamu baca nanti setelah **Tutorial - Pedoman Pengguna** ini. + +**Pedoman Pengguna Lanjutan**, dibangun atas hal ini, menggunakan konsep yang sama, dan mengajarkan kepadamu beberapa fitur tambahan. + +Tetapi kamu harus membaca terlebih dahulu **Tutorial - Pedoman Pengguna** (apa yang sedang kamu baca sekarang). + +Hal ini didesain sehingga kamu dapat membangun aplikasi lengkap dengan hanya **Tutorial - Pedoman Pengguna**, dan kemudian mengembangkannya ke banyak cara yang berbeda, tergantung dari kebutuhanmu, menggunakan beberapa ide-ide tambahan dari **Pedoman Pengguna Lanjutan**. diff --git a/docs/id/mkdocs.yml b/docs/id/mkdocs.yml index d70d2b3c3..abb31252f 100644 --- a/docs/id/mkdocs.yml +++ b/docs/id/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -69,6 +75,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +105,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +119,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +129,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/it/docs/index.md b/docs/it/docs/index.md index c52f07e59..5cbe78a71 100644 --- a/docs/it/docs/index.md +++ b/docs/it/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -318,7 +318,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. diff --git a/docs/it/mkdocs.yml b/docs/it/mkdocs.yml index e6d01fbde..532b5bc52 100644 --- a/docs/it/mkdocs.yml +++ b/docs/it/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -69,6 +75,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +105,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +119,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +129,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/ja/docs/advanced/additional-status-codes.md b/docs/ja/docs/advanced/additional-status-codes.md index 6c03cd92b..d1f8e6451 100644 --- a/docs/ja/docs/advanced/additional-status-codes.md +++ b/docs/ja/docs/advanced/additional-status-codes.md @@ -14,7 +14,7 @@ これを達成するには、 `JSONResponse` をインポートし、 `status_code` を設定して直接内容を返します。 -```Python hl_lines="4 23" +```Python hl_lines="4 25" {!../../../docs_src/additional_status_codes/tutorial001.py!} ``` diff --git a/docs/ja/docs/advanced/conditional-openapi.md b/docs/ja/docs/advanced/conditional-openapi.md new file mode 100644 index 000000000..b892ed6c6 --- /dev/null +++ b/docs/ja/docs/advanced/conditional-openapi.md @@ -0,0 +1,58 @@ +# 条件付き OpenAPI + +必要であれば、設定と環境変数を利用して、環境に応じて条件付きでOpenAPIを構成することが可能です。また、完全にOpenAPIを無効にすることもできます。 + +## セキュリティとAPI、およびドキュメントについて + +本番環境においてドキュメントのUIを非表示にすることによって、APIを保護しようと *すべきではありません*。 + +それは、APIのセキュリティの強化にはならず、*path operations* は依然として利用可能です。 + +もしセキュリティ上の欠陥がソースコードにあるならば、それは存在したままです。 + +ドキュメンテーションを非表示にするのは、単にあなたのAPIへのアクセス方法を難解にするだけでなく、同時にあなた自身の本番環境でのAPIのデバッグを困難にしてしまう可能性があります。単純に、 Security through obscurity の一つの形態として考えられるでしょう。 + +もしあなたのAPIのセキュリティを強化したいなら、いくつかのよりよい方法があります。例を示すと、 + +* リクエストボディとレスポンスのためのPydanticモデルの定義を見直す。 +* 依存関係に基づきすべての必要なパーミッションとロールを設定する。 +* パスワードを絶対に平文で保存しない。パスワードハッシュのみを保存する。 +* PasslibやJWTトークンに代表される、よく知られた暗号化ツールを使って実装する。 +* そして必要なところでは、もっと細かいパーミッション制御をOAuth2スコープを使って行う。 +* など + +それでも、例えば本番環境のような特定の環境のみで、あるいは環境変数の設定によってAPIドキュメントをどうしても無効にしたいという、非常に特殊なユースケースがあるかもしれません。 + +## 設定と環境変数による条件付き OpenAPI + +生成するOpenAPIとドキュメントUIの構成は、共通のPydanticの設定を使用して簡単に切り替えられます。 + +例えば、 + +```Python hl_lines="6 11" +{!../../../docs_src/conditional_openapi/tutorial001.py!} +``` + +ここでは `openapi_url` の設定を、デフォルトの `"/openapi.json"` のまま宣言しています。 + +そして、これを `FastAPI` appを作る際に使います。 + +それから、以下のように `OPENAPI_URL` という環境変数を空文字列に設定することによってOpenAPI (UIドキュメントを含む) を無効化することができます。 + +
+ +```console +$ OPENAPI_URL= uvicorn main:app + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +すると、以下のように `/openapi.json`, `/docs`, `/redoc` のどのURLにアクセスしても、 `404 Not Found` エラーが返ってくるようになります。 + +```JSON +{ + "detail": "Not Found" +} +``` diff --git a/docs/ja/docs/advanced/index.md b/docs/ja/docs/advanced/index.md new file mode 100644 index 000000000..676f60359 --- /dev/null +++ b/docs/ja/docs/advanced/index.md @@ -0,0 +1,24 @@ +# ユーザーガイド 応用編 + +## さらなる機能 + +[チュートリアル - ユーザーガイド](../tutorial/){.internal-link target=_blank}により、**FastAPI**の主要な機能は十分に理解できたことでしょう。 + +以降のセクションでは、チュートリアルでは説明しきれなかったオプションや設定、および機能について説明します。 + +!!! tip "豆知識" + 以降のセクションは、 **必ずしも"応用編"ではありません**。 + + ユースケースによっては、その中から解決策を見つけられるかもしれません。 + +## 先にチュートリアルを読む + +[チュートリアル - ユーザーガイド](../tutorial/){.internal-link target=_blank}の知識があれば、**FastAPI**の主要な機能を利用することができます。 + +以降のセクションは、すでにチュートリアルを読んで、その主要なアイデアを理解できていることを前提としています。 + +## テスト駆動開発のコース + +このセクションの内容を補完するために脱初心者用コースを受けたい場合は、**TestDriven.io**による、Test-Driven Development with FastAPI and Dockerを確認するのがよいかもしれません。 + +現在、このコースで得られた利益の10%が**FastAPI**の開発のために寄付されています。🎉 😄 diff --git a/docs/ja/docs/advanced/nosql-databases.md b/docs/ja/docs/advanced/nosql-databases.md new file mode 100644 index 000000000..fbd76e96b --- /dev/null +++ b/docs/ja/docs/advanced/nosql-databases.md @@ -0,0 +1,156 @@ +# NoSQL (分散 / ビッグデータ) Databases + +**FastAPI** はあらゆる NoSQLと統合することもできます。 + +ここではドキュメントベースのNoSQLデータベースである**Couchbase**を使用した例を見てみましょう。 + +他にもこれらのNoSQLデータベースを利用することが出来ます: + +* **MongoDB** +* **Cassandra** +* **CouchDB** +* **ArangoDB** +* **ElasticSearch** など。 + +!!! tip "豆知識" + **FastAPI**と**Couchbase**を使った公式プロジェクト・ジェネレータがあります。すべて**Docker**ベースで、フロントエンドやその他のツールも含まれています: https://github.com/tiangolo/full-stack-fastapi-couchbase + +## Couchbase コンポーネントの Import + +まずはImportしましょう。今はその他のソースコードに注意を払う必要はありません。 + +```Python hl_lines="3-5" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +## "document type" として利用する定数の定義 + +documentで利用する固定の`type`フィールドを用意しておきます。 + +これはCouchbaseで必須ではありませんが、後々の助けになるベストプラクティスです。 + +```Python hl_lines="9" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +## `Bucket` を取得する関数の追加 + +**Couchbase**では、bucketはdocumentのセットで、様々な種類のものがあります。 + +Bucketは通常、同一のアプリケーション内で互いに関係を持っています。 + +リレーショナルデータベースの世界でいう"database"(データベースサーバではなく特定のdatabase)と類似しています。 + +**MongoDB** で例えると"collection"と似た概念です。 + +次のコードでは主に `Bucket` を利用してCouchbaseを操作します。 + +この関数では以下の処理を行います: + +* **Couchbase** クラスタ(1台の場合もあるでしょう)に接続 + * タイムアウトのデフォルト値を設定 +* クラスタで認証を取得 +* `Bucket` インスタンスを取得 + * タイムアウトのデフォルト値を設定 +* 作成した`Bucket`インスタンスを返却 + +```Python hl_lines="12-21" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +## Pydantic モデルの作成 + +**Couchbase**のdocumentは実際には単にJSONオブジェクトなのでPydanticを利用してモデルに出来ます。 + +### `User` モデル + +まずは`User`モデルを作成してみましょう: + +```Python hl_lines="24-28" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +このモデルは*path operation*に使用するので`hashed_password`は含めません。 + +### `UserInDB` モデル + +それでは`UserInDB`モデルを作成しましょう。 + +こちらは実際にデータベースに保存されるデータを保持します。 + +`User`モデルの持つ全ての属性に加えていくつかの属性を追加するのでPydanticの`BaseModel`を継承せずに`User`のサブクラスとして定義します: + +```Python hl_lines="31-33" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +!!! note "備考" + データベースに保存される`hashed_password`と`type`フィールドを`UserInDB`モデルに保持させていることに注意してください。 + + しかしこれらは(*path operation*で返却する)一般的な`User`モデルには含まれません + +## user の取得 + +それでは次の関数を作成しましょう: + +* username を取得する +* username を利用してdocumentのIDを生成する +* 作成したIDでdocumentを取得する +* documentの内容を`UserInDB`モデルに設定する + +*path operation関数*とは別に、`username`(またはその他のパラメータ)からuserを取得することだけに特化した関数を作成することで、より簡単に複数の部分で再利用したりユニットテストを追加することができます。 + +```Python hl_lines="36-42" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +### f-strings + +`f"userprofile::{username}"` という記載に馴染みがありませんか？これは Python の"f-string"と呼ばれるものです。 + +f-stringの`{}`の中に入れられた変数は、文字列の中に展開/注入されます。 + +### `dict` アンパック + +`UserInDB(**result.value)`という記載に馴染みがありませんか？これは`dict`の"アンパック"と呼ばれるものです。 + +これは`result.value`の`dict`からそのキーと値をそれぞれ取りキーワード引数として`UserInDB`に渡します。 + +例えば`dict`が下記のようになっていた場合: + +```Python +{ + "username": "johndoe", + "hashed_password": "some_hash", +} +``` + +`UserInDB`には次のように渡されます: + +```Python +UserInDB(username="johndoe", hashed_password="some_hash") +``` + +## **FastAPI** コードの実装 + +### `FastAPI` app の作成 + +```Python hl_lines="46" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +### *path operation関数*の作成 + +私たちのコードはCouchbaseを呼び出しており、実験的なPython awaitを使用していないので、私たちは`async def`ではなく通常の`def`で関数を宣言する必要があります。 + +また、Couchbaseは単一の`Bucket`オブジェクトを複数のスレッドで使用しないことを推奨していますので、単に直接Bucketを取得して関数に渡すことが出来ます。 + +```Python hl_lines="49-53" +{!../../../docs_src/nosql_databases/tutorial001.py!} +``` + +## まとめ + +他のサードパーティ製のNoSQLデータベースを利用する場合でも、そのデータベースの標準ライブラリを利用するだけで利用できます。 + +他の外部ツール、システム、APIについても同じことが言えます。 diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md index 27e3c8846..ca6b29a07 100644 --- a/docs/ja/docs/alternatives.md +++ b/docs/ja/docs/alternatives.md @@ -193,7 +193,7 @@ Flask、Flask-apispec、Marshmallow、Webargsの組み合わせは、**FastAPI** * https://github.com/tiangolo/full-stack * https://github.com/tiangolo/full-stack-flask-couchbase -* https://github.com/tiangolo/full-stack-flask-couchdb +* https://github.com/tiangolo/full-stack-flask-couchdb そして、これらのフルスタックジェネレーターは、[**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}の元となっていました。 @@ -295,7 +295,7 @@ OpenAPIやJSON Schemaのような標準に基づいたものではありませ HugはAPIStarに部分的なインスピレーションを与えており、私が発見した中ではAPIStarと同様に最も期待の持てるツールの一つでした。 Hugは、**FastAPI**がPythonの型ヒントを用いてパラメータを宣言し自動的にAPIを定義するスキーマを生成することを触発しました。 - + Hugは、**FastAPI**がヘッダーやクッキーを設定するために関数に `response`引数を宣言することにインスピレーションを与えました。 ### APIStar (<= 0.5) diff --git a/docs/ja/docs/async.md b/docs/ja/docs/async.md index eff4f2f43..8fac2cb38 100644 --- a/docs/ja/docs/async.md +++ b/docs/ja/docs/async.md @@ -361,7 +361,7 @@ async def read_burgers(): この部分は**FastAPI**の仕組みに関する非常に技術的な詳細です。 かなりの技術知識 (コルーチン、スレッド、ブロッキングなど) があり、FastAPIが `async def` と通常の `def` をどのように処理するか知りたい場合は、先に進んでください。 - + ### Path operation 関数 *path operation 関数*を `async def` の代わりに通常の `def` で宣言すると、(サーバーをブロックするので) 直接呼び出す代わりに外部スレッドプール (awaitされる) で実行されます。 diff --git a/docs/ja/docs/deployment/index.md b/docs/ja/docs/deployment/index.md index 2ce81b551..40710a93a 100644 --- a/docs/ja/docs/deployment/index.md +++ b/docs/ja/docs/deployment/index.md @@ -4,4 +4,4 @@ ユースケースや使用しているツールによっていくつかの方法に分かれます。 -次のセクションでより詳しくそれらの方法について説明します。 \ No newline at end of file +次のセクションでより詳しくそれらの方法について説明します。 diff --git a/docs/ja/docs/deployment/manually.md b/docs/ja/docs/deployment/manually.md index 3296ba76f..67010a66f 100644 --- a/docs/ja/docs/deployment/manually.md +++ b/docs/ja/docs/deployment/manually.md @@ -11,7 +11,7 @@
```console - $ pip install uvicorn[standard] + $ pip install "uvicorn[standard]" ---> 100% ``` @@ -20,7 +20,7 @@ !!! tip "豆知識" `standard` を加えることで、Uvicornがインストールされ、いくつかの推奨される依存関係を利用するようになります。 - + これには、`asyncio` の高性能な完全互換品である `uvloop` が含まれ、並行処理のパフォーマンスが大幅に向上します。 === "Hypercorn" diff --git a/docs/ja/docs/fastapi-people.md b/docs/ja/docs/fastapi-people.md index 229d8dde5..11dd656ea 100644 --- a/docs/ja/docs/fastapi-people.md +++ b/docs/ja/docs/fastapi-people.md @@ -115,6 +115,8 @@ FastAPIには、様々なバックグラウンドの人々を歓迎する素晴 彼らは、GitHub Sponsors を介して私の **FastAPI** などに関する活動を支援してくれています。 +{% if sponsors %} + {% if sponsors.gold %} ### Gold Sponsors @@ -142,6 +144,8 @@ FastAPIには、様々なバックグラウンドの人々を歓迎する素晴 {% endfor %} {% endif %} +{% endif %} + ### Individual Sponsors {% if github_sponsors %} diff --git a/docs/ja/docs/features.md b/docs/ja/docs/features.md index 2c406f481..5ea68515d 100644 --- a/docs/ja/docs/features.md +++ b/docs/ja/docs/features.md @@ -193,7 +193,7 @@ FastAPIには非常に使いやすく、非常に強力なしてカスタムの独自ヘッダーを追加できます。 - ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、StarletteのCORSドキュメントに記載されているパラメータ `expose_headers` を使用して、それらをCORS設定に追加する必要があります ([CORS (オリジン間リソース共有)](cors.md){.internal-link target=_blank}) + ただし、ブラウザのクライアントに表示させたいカスタムヘッダーがある場合は、StarletteのCORSドキュメントに記載されているパラメータ `expose_headers` を使用して、それらをCORS設定に追加する必要があります ([CORS (オリジン間リソース共有)](cors.md){.internal-link target=_blank}) !!! note "技術詳細" `from starlette.requests import Request` を使用することもできます。 diff --git a/docs/ja/docs/tutorial/path-params.md b/docs/ja/docs/tutorial/path-params.md index 452ca0c98..66de05afb 100644 --- a/docs/ja/docs/tutorial/path-params.md +++ b/docs/ja/docs/tutorial/path-params.md @@ -139,7 +139,7 @@ Pythonのformat文字列と同様のシンタックスで「パスパラメー ### *パスパラメータ*の宣言 -次に、作成したenumクラスである`ModelName`を使用した型アノテーションをもつ*パスパラメータ*を作成します: +次に、作成したenumクラスである`ModelName`を使用した型アノテーションをもつ*パスパラメータ*を作成します: ```Python hl_lines="16" {!../../../docs_src/path_params/tutorial005.py!} diff --git a/docs/ja/docs/tutorial/query-params-str-validations.md b/docs/ja/docs/tutorial/query-params-str-validations.md index ff0af725f..8d375d7ce 100644 --- a/docs/ja/docs/tutorial/query-params-str-validations.md +++ b/docs/ja/docs/tutorial/query-params-str-validations.md @@ -34,12 +34,12 @@ {!../../../docs_src/query_params_str_validations/tutorial002.py!} ``` -デフォルト値`None`を`Query(None)`に置き換える必要があるので、`Query`の最初の引数はデフォルト値を定義するのと同じです。 +デフォルト値`None`を`Query(default=None)`に置き換える必要があるので、`Query`の最初の引数はデフォルト値を定義するのと同じです。 なので: ```Python -q: Optional[str] = Query(None) +q: Optional[str] = Query(default=None) ``` ...を以下と同じようにパラメータをオプションにします: @@ -60,7 +60,7 @@ q: Optional[str] = None もしくは: ```Python - = Query(None) + = Query(default=None) ``` そして、 `None` を利用することでクエリパラメータが必須ではないと検知します。 @@ -70,7 +70,7 @@ q: Optional[str] = None そして、さらに多くのパラメータを`Query`に渡すことができます。この場合、文字列に適用される、`max_length`パラメータを指定します。 ```Python -q: str = Query(None, max_length=50) +q: Union[str, None] = Query(default=None, max_length=50) ``` これにより、データを検証し、データが有効でない場合は明確なエラーを表示し、OpenAPIスキーマの　*path operation* にパラメータを記載します。 @@ -79,7 +79,7 @@ q: str = Query(None, max_length=50) パラメータ`min_length`も追加することができます: -```Python hl_lines="9" +```Python hl_lines="10" {!../../../docs_src/query_params_str_validations/tutorial003.py!} ``` @@ -87,7 +87,7 @@ q: str = Query(None, max_length=50) パラメータが一致するべき正規表現を定義することができます: -```Python hl_lines="10" +```Python hl_lines="11" {!../../../docs_src/query_params_str_validations/tutorial004.py!} ``` @@ -125,13 +125,13 @@ q: str 以下の代わりに: ```Python -q: Optional[str] = None +q: Union[str, None] = None ``` 現在は以下の例のように`Query`で宣言しています: ```Python -q: Optional[str] = Query(None, min_length=3) +q: Union[str, None] = Query(default=None, min_length=3) ``` そのため、`Query`を使用して必須の値を宣言する必要がある場合は、第一引数に`...`を使用することができます: diff --git a/docs/ja/docs/tutorial/query-params.md b/docs/ja/docs/tutorial/query-params.md index 91783a53a..9f8c6ab9f 100644 --- a/docs/ja/docs/tutorial/query-params.md +++ b/docs/ja/docs/tutorial/query-params.md @@ -18,7 +18,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10 ...クエリパラメータは: * `skip`: 値は `0` -* `limit`: 値は `10` +* `limit`: 値は `10` これらはURLの一部なので、「自然に」文字列になります。 @@ -75,7 +75,7 @@ http://127.0.0.1:8000/items/?skip=20 !!! note "備考" FastAPIは、`= None`があるおかげで、`q`がオプショナルだとわかります。 - + `Optional[str]` の`Optional` はFastAPIでは使用されていません（FastAPIは`str`の部分のみ使用します）。しかし、`Optional[str]` はエディタがコードのエラーを見つけるのを助けてくれます。 ## クエリパラメータの型変換 @@ -116,7 +116,7 @@ http://127.0.0.1:8000/items/foo?short=on http://127.0.0.1:8000/items/foo?short=yes ``` -もしくは、他の大文字小文字のバリエーション (アッパーケース、最初の文字だけアッパーケース、など)で、関数は `short` パラメータを `True` な `bool` 値として扱います。それ以外は `False` になります。 +もしくは、他の大文字小文字のバリエーション (アッパーケース、最初の文字だけアッパーケース、など)で、関数は `short` パラメータを `True` な `bool` 値として扱います。それ以外は `False` になります。 ## 複数のパスパラメータとクエリパラメータ diff --git a/docs/ja/docs/tutorial/request-forms.md b/docs/ja/docs/tutorial/request-forms.md index 06105c9ef..bce6e8d9a 100644 --- a/docs/ja/docs/tutorial/request-forms.md +++ b/docs/ja/docs/tutorial/request-forms.md @@ -45,7 +45,7 @@ HTMLフォーム（`
`）がサーバにデータを送信する方 フォームからのデータは通常、`application/x-www-form-urlencoded`の「media type」を使用してエンコードされます。 しかし、フォームがファイルを含む場合は、`multipart/form-data`としてエンコードされます。ファイルの扱いについては次の章で説明します。 - + これらのエンコーディングやフォームフィールドの詳細については、MDNのPOSTのウェブドキュメントを参照してください。 !!! warning "注意" diff --git a/docs/ja/docs/tutorial/static-files.md b/docs/ja/docs/tutorial/static-files.md index fcc3ba924..1d9c434c3 100644 --- a/docs/ja/docs/tutorial/static-files.md +++ b/docs/ja/docs/tutorial/static-files.md @@ -2,20 +2,6 @@ `StaticFiles` を使用して、ディレクトリから静的ファイルを自動的に提供できます。 -## `aiofiles` をインストール - -まず、`aiofiles` をインストールする必要があります: - -
- -```console -$ pip install aiofiles - ----> 100% -``` - -
- ## `StaticFiles` の使用 * `StaticFiles` をインポート。 diff --git a/docs/ja/docs/tutorial/testing.md b/docs/ja/docs/tutorial/testing.md index ebd2de37c..03b0e1dee 100644 --- a/docs/ja/docs/tutorial/testing.md +++ b/docs/ja/docs/tutorial/testing.md @@ -36,7 +36,7 @@ !!! tip "豆知識" FastAPIアプリケーションへのリクエストの送信とは別に、テストで `async` 関数 (非同期データベース関数など) を呼び出したい場合は、高度なチュートリアルの[Async Tests](../advanced/async-tests.md){.internal-link target=_blank} を参照してください。 - + ## テストの分離 実際のアプリケーションでは、おそらくテストを別のファイルに保存します。 @@ -74,16 +74,24 @@ これらの *path operation* には `X-Token` ヘッダーが必要です。 -```Python -{!../../../docs_src/app_testing/main_b.py!} -``` +=== "Python 3.6 and above" + + ```Python + {!> ../../../docs_src/app_testing/app_b/main.py!} + ``` + +=== "Python 3.10 and above" + + ```Python + {!> ../../../docs_src/app_testing/app_b_py310/main.py!} + ``` ### 拡張版テストファイル 次に、先程のものに拡張版のテストを加えた、`test_main_b.py` を作成します。 ```Python -{!../../../docs_src/app_testing/test_main_b.py!} +{!> ../../../docs_src/app_testing/app_b/test_main.py!} ``` リクエストに情報を渡せるクライアントが必要で、その方法がわからない場合はいつでも、`requests` での実現方法を検索 (Google) できます。 @@ -104,7 +112,7 @@ `TestClient` は、Pydanticモデルではなく、JSONに変換できるデータを受け取ることに注意してください。 テストにPydanticモデルがあり、テスト中にそのデータをアプリケーションに送信したい場合は、[JSON互換エンコーダ](encoder.md){.internal-link target=_blank} で説明されている `jsonable_encoder` が利用できます。 - + ## 実行 後は、`pytest` をインストールするだけです: diff --git a/docs/ja/mkdocs.yml b/docs/ja/mkdocs.yml index 39fd8a211..b3f18bbdd 100644 --- a/docs/ja/mkdocs.yml +++ b/docs/ja/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -74,10 +80,13 @@ nav: - tutorial/testing.md - tutorial/debugging.md - 高度なユーザーガイド: + - advanced/index.md - advanced/path-operation-advanced-configuration.md - advanced/additional-status-codes.md - advanced/response-directly.md - advanced/custom-response.md + - advanced/nosql-databases.md + - advanced/conditional-openapi.md - async.md - デプロイ: - deployment/index.md @@ -109,6 +118,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -137,8 +148,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -147,6 +162,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -155,6 +172,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/ko/docs/deployment/versions.md b/docs/ko/docs/deployment/versions.md index 4c1bcdc2e..074c15158 100644 --- a/docs/ko/docs/deployment/versions.md +++ b/docs/ko/docs/deployment/versions.md @@ -6,7 +6,7 @@ 이것이 아직도 최신 버전이 `0.x.x`인 이유입니다. 이것은 각각의 버전들이 잠재적으로 변할 수 있다는 것을 보여줍니다. 이는 유의적 버전 관습을 따릅니다. -지금 바로 **FastAPI**로 응용 프로그램을 만들 수 있습니다. 이때 (아마 지금까지 그래 왔던 것처럼), 사용하는 버전이 코드와 잘 맞는지 확인해야합니다. +지금 바로 **FastAPI**로 응용 프로그램을 만들 수 있습니다. 이때 (아마 지금까지 그래 왔던 것처럼), 사용하는 버전이 코드와 잘 맞는지 확인해야합니다. ## `fastapi` 버전을 표시 @@ -46,7 +46,7 @@ FastAPI는 오류를 수정하고, 일반적인 변경사항을 위해 "패치" !!! tip "팁" 여기서 말하는 "패치"란 버전의 마지막 숫자로, 예를 들어 `0.2.3` 버전에서 "패치"는 `3`을 의미합니다. -따라서 다음과 같이 버전을 표시할 수 있습니다: +따라서 다음과 같이 버전을 표시할 수 있습니다: ```txt fastapi>=0.45.0,<0.46.0 @@ -71,7 +71,7 @@ fastapi>=0.45.0,<0.46.0 `starlette`의 버전은 표시할 수 없습니다. -서로다른 버전의 **FastAPI**가 구체적이고 새로운 버전의 Starlette을 사용할 것입니다. +서로다른 버전의 **FastAPI**가 구체적이고 새로운 버전의 Starlette을 사용할 것입니다. 그러므로 **FastAPI**가 알맞은 Starlette 버전을 사용하도록 하십시오. diff --git a/docs/ko/docs/index.md b/docs/ko/docs/index.md index d0c236906..5a258f47b 100644 --- a/docs/ko/docs/index.md +++ b/docs/ko/docs/index.md @@ -131,7 +131,7 @@ $ pip install fastapi
```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -145,7 +145,7 @@ $ pip install uvicorn[standard] * `main.py` 파일을 만드십시오: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -158,7 +158,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -168,7 +168,7 @@ def read_item(item_id: int, q: Optional[str] = None): 여러분의 코드가 `async` / `await`을 사용한다면, `async def`를 사용하십시오. ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -181,7 +181,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -260,7 +260,7 @@ INFO: Application startup complete. Pydantic을 이용해 파이썬 표준 타입으로 본문을 선언합니다. ```Python hl_lines="4 9 10 11 12 25 26 27" -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -271,7 +271,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -280,7 +280,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -443,7 +443,6 @@ Pydantic이 사용하는: Starlette이 사용하는: * requests - `TestClient`를 사용하려면 필요. -* aiofiles - `FileResponse` 또는 `StaticFiles`를 사용하려면 필요. * jinja2 - 기본 템플릿 설정을 사용하려면 필요. * python-multipart - `request.form()`과 함께 "parsing"의 지원을 원하면 필요. * itsdangerous - `SessionMiddleware` 지원을 위해 필요. diff --git a/docs/ko/docs/tutorial/header-params.md b/docs/ko/docs/tutorial/header-params.md index 1c46b32ba..484554e97 100644 --- a/docs/ko/docs/tutorial/header-params.md +++ b/docs/ko/docs/tutorial/header-params.md @@ -57,7 +57,7 @@ 타입 정의에서 리스트를 사용하여 이러한 케이스를 정의할 수 있습니다. -중복 헤더의 모든 값을 파이썬 `list`로 수신합니다. +중복 헤더의 모든 값을 파이썬 `list`로 수신합니다. 예를 들어, 두 번 이상 나타날 수 있는 `X-Token`헤더를 선언하려면, 다음과 같이 작성합니다: diff --git a/docs/ko/docs/tutorial/index.md b/docs/ko/docs/tutorial/index.md index 622aad1aa..d6db525e8 100644 --- a/docs/ko/docs/tutorial/index.md +++ b/docs/ko/docs/tutorial/index.md @@ -43,7 +43,7 @@ $ uvicorn main:app --reload
```console -$ pip install fastapi[all] +$ pip install "fastapi[all]" ---> 100% ``` diff --git a/docs/ko/docs/tutorial/path-params-numeric-validations.md b/docs/ko/docs/tutorial/path-params-numeric-validations.md index abb9d03db..cadf543fc 100644 --- a/docs/ko/docs/tutorial/path-params-numeric-validations.md +++ b/docs/ko/docs/tutorial/path-params-numeric-validations.md @@ -43,7 +43,7 @@ 따라서 함수를 다음과 같이 선언 할 수 있습니다: -```Python hl_lines="8" +```Python hl_lines="7" {!../../../docs_src/path_params_numeric_validations/tutorial002.py!} ``` @@ -55,7 +55,7 @@ 파이썬은 `*`으로 아무런 행동도 하지 않지만, 따르는 매개변수들은 kwargs로도 알려진 키워드 인자(키-값 쌍)여야 함을 인지합니다. 기본값을 가지고 있지 않더라도 그렇습니다. -```Python hl_lines="8" +```Python hl_lines="7" {!../../../docs_src/path_params_numeric_validations/tutorial003.py!} ``` diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md index ede63f69d..5cf397e7a 100644 --- a/docs/ko/docs/tutorial/path-params.md +++ b/docs/ko/docs/tutorial/path-params.md @@ -241,4 +241,4 @@ Starlette에서 직접 옵션을 사용하면 다음과 같은 URL을 사용하 위 사항들을 그저 한번에 선언하면 됩니다. -이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다. \ No newline at end of file +이는 (원래 성능과는 별개로) 대체 프레임워크와 비교했을 때 **FastAPI**의 주요 가시적 장점일 것입니다. diff --git a/docs/ko/docs/tutorial/query-params.md b/docs/ko/docs/tutorial/query-params.md index 05f2ff9c9..bb631e6ff 100644 --- a/docs/ko/docs/tutorial/query-params.md +++ b/docs/ko/docs/tutorial/query-params.md @@ -75,7 +75,7 @@ http://127.0.0.1:8000/items/?skip=20 !!! note "참고" FastAPI는 `q`가 `= None`이므로 선택적이라는 것을 인지합니다. - `Optional[str]`에 있는 `Optional`은 FastAPI(FastAPI는 `str` 부분만 사용합니다)가 사용하는게 아니지만, `Optional[str]`은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다. + `Union[str, None]`에 있는 `Union`은 FastAPI(FastAPI는 `str` 부분만 사용합니다)가 사용하는게 아니지만, `Union[str, None]`은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다. ## 쿼리 매개변수 형변환 diff --git a/docs/ko/docs/tutorial/request-files.md b/docs/ko/docs/tutorial/request-files.md index 769a676cd..decefe981 100644 --- a/docs/ko/docs/tutorial/request-files.md +++ b/docs/ko/docs/tutorial/request-files.md @@ -13,7 +13,7 @@ `fastapi` 에서 `File` 과 `UploadFile` 을 임포트 합니다: -```Python hl_lines="1" +```Python hl_lines="1" {!../../../docs_src/request_files/tutorial001.py!} ``` @@ -21,7 +21,7 @@ `Body` 및 `Form` 과 동일한 방식으로 파일의 매개변수를 생성합니다: -```Python hl_lines="7" +```Python hl_lines="7" {!../../../docs_src/request_files/tutorial001.py!} ``` @@ -45,7 +45,7 @@ `File` 매개변수를 `UploadFile` 타입으로 정의합니다: -```Python hl_lines="12" +```Python hl_lines="12" {!../../../docs_src/request_files/tutorial001.py!} ``` @@ -97,7 +97,7 @@ contents = myfile.file.read() ## "폼 데이터"란 -HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 대개 데이터에 JSON과는 다른 "특별한" 인코딩을 사용합니다. +HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 대개 데이터에 JSON과는 다른 "특별한" 인코딩을 사용합니다. **FastAPI**는 JSON 대신 올바른 위치에서 데이터를 읽을 수 있도록 합니다. @@ -121,7 +121,7 @@ HTML의 폼들(`
`)이 서버에 데이터를 전송하는 방식은 이 기능을 사용하기 위해 , `bytes` 의 `List` 또는 `UploadFile` 를 선언하기 바랍니다: -```Python hl_lines="10 15" +```Python hl_lines="10 15" {!../../../docs_src/request_files/tutorial002.py!} ``` diff --git a/docs/ko/docs/tutorial/request-forms-and-files.md b/docs/ko/docs/tutorial/request-forms-and-files.md index 6750c7b23..ddf232e7f 100644 --- a/docs/ko/docs/tutorial/request-forms-and-files.md +++ b/docs/ko/docs/tutorial/request-forms-and-files.md @@ -9,7 +9,7 @@ ## `File` 및 `Form` 업로드 -```Python hl_lines="1" +```Python hl_lines="1" {!../../../docs_src/request_forms_and_files/tutorial001.py!} ``` @@ -17,7 +17,7 @@ `Body` 및 `Query`와 동일한 방식으로 파일과 폼의 매개변수를 생성합니다: -```Python hl_lines="8" +```Python hl_lines="8" {!../../../docs_src/request_forms_and_files/tutorial001.py!} ``` diff --git a/docs/ko/docs/tutorial/response-status-code.md b/docs/ko/docs/tutorial/response-status-code.md index d201867a1..f92c057be 100644 --- a/docs/ko/docs/tutorial/response-status-code.md +++ b/docs/ko/docs/tutorial/response-status-code.md @@ -8,11 +8,11 @@ * `@app.delete()` * 기타 -```Python hl_lines="6" +```Python hl_lines="6" {!../../../docs_src/response_status_code/tutorial001.py!} ``` -!!! note "참고" +!!! note "참고" `status_code` 는 "데코레이터" 메소드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수들과 본문처럼 *경로 작동 함수*가 아닙니다. `status_code` 매개변수는 HTTP 상태 코드를 숫자로 입력받습니다. @@ -27,7 +27,7 @@ -!!! note "참고" +!!! note "참고" 어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고). 이에 따라 FastAPI는 응답 본문이 없음을 명시하는 OpenAPI를 생성합니다. @@ -61,7 +61,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다 상기 예시 참고: -```Python hl_lines="6" +```Python hl_lines="6" {!../../../docs_src/response_status_code/tutorial001.py!} ``` @@ -71,7 +71,7 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다 `fastapi.status` 의 편의 변수를 사용할 수 있습니다. -```Python hl_lines="1 6" +```Python hl_lines="1 6" {!../../../docs_src/response_status_code/tutorial002.py!} ``` diff --git a/docs/ko/mkdocs.yml b/docs/ko/mkdocs.yml index 1d4d30913..50931e134 100644 --- a/docs/ko/mkdocs.yml +++ b/docs/ko/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -62,6 +68,7 @@ nav: - tutorial/response-status-code.md - tutorial/request-files.md - tutorial/request-forms-and-files.md + - tutorial/encoder.md markdown_extensions: - toc: permalink: true @@ -79,6 +86,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -107,8 +116,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -117,6 +130,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -125,6 +140,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/nl/docs/index.md b/docs/nl/docs/index.md new file mode 100644 index 000000000..fd52f994c --- /dev/null +++ b/docs/nl/docs/index.md @@ -0,0 +1,468 @@ + +{!../../../docs/missing-translation.md!} + + +

+ FastAPI +

+

+ FastAPI framework, high performance, easy to learn, fast to code, ready for production +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**Documentation**: https://fastapi.tiangolo.com + +**Source Code**: https://github.com/tiangolo/fastapi + +--- + +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints. + +The key features are: + +* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). + +* **Fast to code**: Increase the speed to develop features by about 200% to 300%. * +* **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * +* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. +* **Easy**: Designed to be easy to use and learn. Less time reading docs. +* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. +* **Robust**: Get production-ready code. With automatic interactive documentation. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. + +* estimation based on tests on an internal development team, building production applications. + +## Sponsors + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +Other sponsors + +## Opinions + +"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" + +
Kabir Khan - Microsoft (ref)
+ +--- + +"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" + +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +"_I’m over the moon excited about **FastAPI**. It’s so fun!_" + +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" + +
Timothy Crosley - Hug creator (ref)
+ +--- + +"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" + +"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, the FastAPI of CLIs + + + +If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**. + +**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀 + +## Requirements + +Python 3.6+ + +FastAPI stands on the shoulders of giants: + +* Starlette for the web parts. +* Pydantic for the data parts. + +## Installation + +
+ +```console +$ pip install fastapi + +---> 100% +``` + +
+ +You will also need an ASGI server, for production such as Uvicorn or Hypercorn. + +
+ +```console +$ pip install "uvicorn[standard]" + +---> 100% +``` + +
+ +## Example + +### Create it + +* Create a file `main.py` with: + +```Python +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+Or use async def... + +If your code uses `async` / `await`, use `async def`: + +```Python hl_lines="9 14" +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +**Note**: + +If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs. + +
+ +### Run it + +Run the server with: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +
+About the command uvicorn main:app --reload... + +The command `uvicorn main:app` refers to: + +* `main`: the file `main.py` (the Python "module"). +* `app`: the object created inside of `main.py` with the line `app = FastAPI()`. +* `--reload`: make the server restart after code changes. Only do this for development. + +
+ +### Check it + +Open your browser at http://127.0.0.1:8000/items/5?q=somequery. + +You will see the JSON response as: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +You already created an API that: + +* Receives HTTP requests in the _paths_ `/` and `/items/{item_id}`. +* Both _paths_ take `GET` operations (also known as HTTP _methods_). +* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`. +* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`. + +### Interactive API docs + +Now go to http://127.0.0.1:8000/docs. + +You will see the automatic interactive API documentation (provided by Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Alternative API docs + +And now, go to http://127.0.0.1:8000/redoc. + +You will see the alternative automatic documentation (provided by ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## Example upgrade + +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 + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Union[bool, None] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +The server should reload automatically (because you added `--reload` to the `uvicorn` command above). + +### Interactive API docs upgrade + +Now go to http://127.0.0.1:8000/docs. + +* The interactive API documentation will be automatically updated, including the new body: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### Alternative API docs upgrade + +And now, go to http://127.0.0.1:8000/redoc. + +* The alternative documentation will also reflect the new query parameter and body: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Recap + +In summary, you declare **once** the types of parameters, body, etc. as function parameters. + +You do that with standard modern Python types. + +You don't have to learn a new syntax, the methods or classes of a specific library, etc. + +Just standard **Python 3.6+**. + +For example, for an `int`: + +```Python +item_id: int +``` + +or for a more complex `Item` model: + +```Python +item: Item +``` + +...and with that single declaration you get: + +* Editor support, including: + * Completion. + * Type checks. +* Validation of data: + * Automatic and clear errors when the data is invalid. + * Validation even for deeply nested JSON objects. +* Conversion of input data: coming from the network to Python data and types. Reading from: + * JSON. + * Path parameters. + * Query parameters. + * Cookies. + * Headers. + * Forms. + * Files. +* Conversion of output data: converting from Python data and types to network data (as JSON): + * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). + * `datetime` objects. + * `UUID` objects. + * Database models. + * ...and many more. +* Automatic interactive API documentation, including 2 alternative user interfaces: + * Swagger UI. + * ReDoc. + +--- + +Coming back to the previous code example, **FastAPI** will: + +* Validate that there is an `item_id` in the path for `GET` and `PUT` requests. +* Validate that the `item_id` is of type `int` for `GET` and `PUT` requests. + * If it is not, the client will see a useful, clear error. +* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests. + * As the `q` parameter is declared with `= None`, it is optional. + * Without the `None` it would be required (as is the body in the case with `PUT`). +* For `PUT` requests to `/items/{item_id}`, Read the body as JSON: + * Check that it has a required attribute `name` that should be a `str`. + * Check that it has a required attribute `price` that has to be a `float`. + * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present. + * All this would also work for deeply nested JSON objects. +* Convert from and to JSON automatically. +* Document everything with OpenAPI, that can be used by: + * Interactive documentation systems. + * Automatic client code generation systems, for many languages. +* Provide 2 interactive documentation web interfaces directly. + +--- + +We just scratched the surface, but you already get the idea of how it all works. + +Try changing the line with: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...from: + +```Python + ... "item_name": item.name ... +``` + +...to: + +```Python + ... "item_price": item.price ... +``` + +...and see how your editor will auto-complete the attributes and know their types: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +For a more complete example including more features, see the Tutorial - User Guide. + +**Spoiler alert**: the tutorial - user guide includes: + +* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**. +* How to set **validation constraints** as `maximum_length` or `regex`. +* A very powerful and easy to use **Dependency Injection** system. +* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. +* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). +* **GraphQL** integration with Strawberry and other libraries. +* Many extra features (thanks to Starlette) as: + * **WebSockets** + * extremely easy tests based on `requests` and `pytest` + * **CORS** + * **Cookie Sessions** + * ...and more. + +## Performance + +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) + +To understand more about it, see the section Benchmarks. + +## Optional Dependencies + +Used by Pydantic: + +* ujson - for faster JSON "parsing". +* email_validator - for email validation. + +Used by Starlette: + +* requests - Required if you want to use the `TestClient`. +* jinja2 - Required if you want to use the default template configuration. +* python-multipart - Required if you want to support form "parsing", with `request.form()`. +* itsdangerous - Required for `SessionMiddleware` support. +* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). +* ujson - Required if you want to use `UJSONResponse`. + +Used by FastAPI / Starlette: + +* uvicorn - for the server that loads and serves your application. +* orjson - Required if you want to use `ORJSONResponse`. + +You can install all of these with `pip install "fastapi[all]"`. + +## License + +This project is licensed under the terms of the MIT license. diff --git a/docs/nl/mkdocs.yml b/docs/nl/mkdocs.yml new file mode 100644 index 000000000..6d46939f9 --- /dev/null +++ b/docs/nl/mkdocs.yml @@ -0,0 +1,145 @@ +site_name: FastAPI +site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production +site_url: https://fastapi.tiangolo.com/nl/ +theme: + name: material + custom_dir: overrides + palette: + - media: '(prefers-color-scheme: light)' + scheme: default + primary: teal + accent: amber + toggle: + icon: material/lightbulb + name: Switch to light mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + primary: teal + accent: amber + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + features: + - search.suggest + - search.highlight + - content.tabs.link + icon: + repo: fontawesome/brands/github-alt + logo: https://fastapi.tiangolo.com/img/icon-white.svg + favicon: https://fastapi.tiangolo.com/img/favicon.png + language: nl +repo_name: tiangolo/fastapi +repo_url: https://github.com/tiangolo/fastapi +edit_uri: '' +plugins: +- search +- markdownextradata: + data: data +nav: +- FastAPI: index.md +- Languages: + - en: / + - az: /az/ + - de: /de/ + - es: /es/ + - fa: /fa/ + - fr: /fr/ + - he: /he/ + - id: /id/ + - it: /it/ + - ja: /ja/ + - ko: /ko/ + - nl: /nl/ + - pl: /pl/ + - pt: /pt/ + - ru: /ru/ + - sq: /sq/ + - sv: /sv/ + - tr: /tr/ + - uk: /uk/ + - zh: /zh/ +markdown_extensions: +- toc: + permalink: true +- markdown.extensions.codehilite: + guess_lang: false +- mdx_include: + base_path: docs +- admonition +- codehilite +- extra +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format '' +- pymdownx.tabbed: + alternate_style: true +- attr_list +- md_in_html +extra: + analytics: + provider: google + property: UA-133183413-1 + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/tiangolo/fastapi + - icon: fontawesome/brands/discord + link: https://discord.gg/VQjSZaeJmf + - icon: fontawesome/brands/twitter + link: https://twitter.com/fastapi + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/tiangolo + - icon: fontawesome/brands/dev + link: https://dev.to/tiangolo + - icon: fontawesome/brands/medium + link: https://medium.com/@tiangolo + - icon: fontawesome/solid/globe + link: https://tiangolo.com + alternate: + - link: / + name: en - English + - link: /az/ + name: az + - link: /de/ + name: de + - link: /es/ + name: es - español + - link: /fa/ + name: fa + - link: /fr/ + name: fr - français + - link: /he/ + name: he + - link: /id/ + name: id + - link: /it/ + name: it - italiano + - link: /ja/ + name: ja - 日本語 + - link: /ko/ + name: ko - 한국어 + - link: /nl/ + name: nl + - link: /pl/ + name: pl + - link: /pt/ + name: pt - português + - link: /ru/ + name: ru - русский язык + - link: /sq/ + name: sq - shqip + - link: /sv/ + name: sv - svenska + - link: /tr/ + name: tr - Türkçe + - link: /uk/ + name: uk - українська мова + - link: /zh/ + name: zh - 汉语 +extra_css: +- https://fastapi.tiangolo.com/css/termynal.css +- https://fastapi.tiangolo.com/css/custom.css +extra_javascript: +- https://fastapi.tiangolo.com/js/termynal.js +- https://fastapi.tiangolo.com/js/custom.js diff --git a/docs/nl/overrides/.gitignore b/docs/nl/overrides/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/pl/docs/index.md b/docs/pl/docs/index.md index 4a300ae63..9cc99ba72 100644 --- a/docs/pl/docs/index.md +++ b/docs/pl/docs/index.md @@ -130,7 +130,7 @@ Na serwerze produkcyjnym będziesz także potrzebował serwera ASGI, np. ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -144,7 +144,7 @@ $ pip install uvicorn[standard] * Utwórz plik o nazwie `main.py` z: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -157,7 +157,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -167,7 +167,7 @@ def read_item(item_id: int, q: Optional[str] = None): Jeżeli twój kod korzysta z `async` / `await`, użyj `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -180,7 +180,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -258,7 +258,7 @@ Zmodyfikuj teraz plik `main.py`, aby otrzmywał treść (body) żądania `PUT`. Zadeklaruj treść żądania, używając standardowych typów w Pythonie dzięki Pydantic. ```Python hl_lines="4 9-12 25-27" -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -269,7 +269,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -278,7 +278,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} diff --git a/docs/pl/docs/tutorial/first-steps.md b/docs/pl/docs/tutorial/first-steps.md new file mode 100644 index 000000000..9406d703d --- /dev/null +++ b/docs/pl/docs/tutorial/first-steps.md @@ -0,0 +1,334 @@ +# Pierwsze kroki + +Najprostszy plik FastAPI może wyglądać tak: + +```Python +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Skopiuj to do pliku `main.py`. + +Uruchom serwer: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +!!! note + Polecenie `uvicorn main:app` odnosi się do: + + * `main`: plik `main.py` ("moduł" Python). + * `app`: obiekt utworzony w pliku `main.py` w lini `app = FastAPI()`. + * `--reload`: sprawia, że serwer uruchamia się ponownie po zmianie kodu. Używany tylko w trakcie tworzenia oprogramowania. + +Na wyjściu znajduje się linia z czymś w rodzaju: + +```hl_lines="4" +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +Ta linia pokazuje adres URL, pod którym Twoja aplikacja jest obsługiwana, na Twoim lokalnym komputerze. + +### Sprawdź to + +Otwórz w swojej przeglądarce http://127.0.0.1:8000. + +Zobaczysz odpowiedź w formacie JSON: + +```JSON +{"message": "Hello World"} +``` + +### Interaktywna dokumentacja API + +Przejdź teraz do http://127.0.0.1:8000/docs. + +Zobaczysz automatyczną i interaktywną dokumentację API (dostarczoną przez Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Alternatywna dokumentacja API + +Teraz przejdź do http://127.0.0.1:8000/redoc. + +Zobaczysz alternatywną automatycznie wygenerowaną dokumentację API (dostarczoną przez ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +### OpenAPI + +**FastAPI** generuje "schemat" z całym Twoim API przy użyciu standardu **OpenAPI** służącego do definiowania API. + +#### Schema + +"Schema" jest definicją lub opisem czegoś. Nie jest to kod, który go implementuje, ale po prostu abstrakcyjny opis. + +#### API "Schema" + +W typ przypadku, OpenAPI to specyfikacja, która dyktuje sposób definiowania schematu interfejsu API. + +Definicja schematu zawiera ścieżki API, możliwe parametry, które są przyjmowane przez endpointy, itp. + +#### "Schemat" danych + +Termin "schemat" może również odnosić się do wyglądu niektórych danych, takich jak zawartość JSON. + +W takim przypadku będzie to oznaczać atrybuty JSON, ich typy danych itp. + +#### OpenAPI i JSON Schema + +OpenAPI definiuje API Schema dla Twojego API, który zawiera definicje (lub "schematy") danych wysyłanych i odbieranych przez Twój interfejs API przy użyciu **JSON Schema**, standardu dla schematów danych w formacie JSON. + +#### Sprawdź `openapi.json` + +Jeśli jesteś ciekawy, jak wygląda surowy schemat OpenAPI, FastAPI automatycznie generuje JSON Schema z opisami wszystkich Twoich API. + +Możesz to zobaczyć bezpośrednio pod adresem: http://127.0.0.1:8000/openapi.json. + +Zobaczysz JSON zaczynający się od czegoś takiego: + +```JSON +{ + "openapi": "3.0.2", + "info": { + "title": "FastAPI", + "version": "0.1.0" + }, + "paths": { + "/items/": { + "get": { + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + + + +... +``` + +#### Do czego służy OpenAPI + +Schemat OpenAPI jest tym, co zasila dwa dołączone interaktywne systemy dokumentacji. + +Istnieją dziesiątki alternatyw, wszystkie oparte na OpenAPI. Możesz łatwo dodać dowolną z nich do swojej aplikacji zbudowanej za pomocą **FastAPI**. + +Możesz go również użyć do automatycznego generowania kodu dla klientów, którzy komunikują się z Twoim API. Na przykład aplikacje frontendowe, mobilne lub IoT. + +## Przypomnijmy, krok po kroku + +### Krok 1: zaimportuj `FastAPI` + +```Python hl_lines="1" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +`FastAPI` jest klasą, która zapewnia wszystkie funkcjonalności Twojego API. + +!!! note "Szczegóły techniczne" + `FastAPI` jest klasą, która dziedziczy bezpośrednio z `Starlette`. + + Oznacza to, że możesz korzystać ze wszystkich funkcjonalności Starlette również w `FastAPI`. + + +### Krok 2: utwórz instancję `FastAPI` + +```Python hl_lines="3" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Zmienna `app` będzie tutaj "instancją" klasy `FastAPI`. + +Będzie to główny punkt interakcji przy tworzeniu całego interfejsu API. + +Ta zmienna `app` jest tą samą zmienną, do której odnosi się `uvicorn` w poleceniu: + +
+ +```console +$ uvicorn main:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +Jeśli stworzysz swoją aplikację, np.: + +```Python hl_lines="3" +{!../../../docs_src/first_steps/tutorial002.py!} +``` + +I umieścisz to w pliku `main.py`, to będziesz mógł tak wywołać `uvicorn`: + +
+ +```console +$ uvicorn main:my_awesome_api --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### Krok 3: wykonaj *operację na ścieżce* + +#### Ścieżka + +"Ścieżka" tutaj odnosi się do ostatniej części adresu URL, zaczynając od pierwszego `/`. + +Więc, w adresie URL takim jak: + +``` +https://example.com/items/foo +``` + +...ścieżką będzie: + +``` +/items/foo +``` + +!!! info + "Ścieżka" jest zazwyczaj nazywana "path", "endpoint" lub "route'. + +Podczas budowania API, "ścieżka" jest głównym sposobem na oddzielenie "odpowiedzialności" i „zasobów”. + +#### Operacje + +"Operacje" tutaj odnoszą się do jednej z "metod" HTTP. + +Jedna z: + +* `POST` +* `GET` +* `PUT` +* `DELETE` + +...i te bardziej egzotyczne: + +* `OPTIONS` +* `HEAD` +* `PATCH` +* `TRACE` + +W protokole HTTP można komunikować się z każdą ścieżką za pomocą jednej (lub więcej) "metod". + +--- + +Podczas tworzenia API zwykle używasz tych metod HTTP do wykonania określonej akcji. + +Zazwyczaj używasz: + +* `POST`: do tworzenia danych. +* `GET`: do odczytywania danych. +* `PUT`: do aktualizacji danych. +* `DELETE`: do usuwania danych. + +Tak więc w OpenAPI każda z metod HTTP nazywana jest "operacją". + +Będziemy je również nazywali "**operacjami**". + +#### Zdefiniuj *dekorator operacji na ścieżce* + +```Python hl_lines="6" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +`@app.get("/")` mówi **FastAPI** że funkcja poniżej odpowiada za obsługę żądań, które trafiają do: + +* ścieżki `/` +* używając operacji get + +!!! info "`@decorator` Info" + Składnia `@something` jest w Pythonie nazywana "dekoratorem". + + Umieszczasz to na szczycie funkcji. Jak ładną ozdobną czapkę (chyba stąd wzięła się nazwa). + + "Dekorator" przyjmuje funkcję znajdującą się poniżej jego i coś z nią robi. + + W naszym przypadku dekorator mówi **FastAPI**, że poniższa funkcja odpowiada **ścieżce** `/` z **operacją** `get`. + + Jest to "**dekorator operacji na ścieżce**". + +Możesz również użyć innej operacji: + +* `@app.post()` +* `@app.put()` +* `@app.delete()` + +Oraz tych bardziej egzotycznych: + +* `@app.options()` +* `@app.head()` +* `@app.patch()` +* `@app.trace()` + +!!! tip + Możesz dowolnie używać każdej operacji (metody HTTP). + + **FastAPI** nie narzuca żadnego konkretnego znaczenia. + + Informacje tutaj są przedstawione jako wskazówka, a nie wymóg. + + Na przykład, używając GraphQL, normalnie wykonujesz wszystkie akcje używając tylko operacji `POST`. + +### Krok 4: zdefiniuj **funkcję obsługującą ścieżkę** + +To jest nasza "**funkcja obsługująca ścieżkę**": + +* **ścieżka**: to `/`. +* **operacja**: to `get`. +* **funkcja**: to funkcja poniżej "dekoratora" (poniżej `@app.get("/")`). + +```Python hl_lines="7" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Jest to funkcja Python. + +Zostanie ona wywołana przez **FastAPI** za każdym razem, gdy otrzyma żądanie do adresu URL "`/`" przy użyciu operacji `GET`. + +W tym przypadku jest to funkcja "asynchroniczna". + +--- + +Możesz również zdefiniować to jako normalną funkcję zamiast `async def`: + +```Python hl_lines="7" +{!../../../docs_src/first_steps/tutorial003.py!} +``` + +!!! note + Jeśli nie znasz różnicy, sprawdź [Async: *"In a hurry?"*](/async/#in-a-hurry){.internal-link target=_blank}. + +### Krok 5: zwróć zawartość + +```Python hl_lines="8" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Możesz zwrócić `dict`, `list`, pojedynczą wartość jako `str`, `int`, itp. + +Możesz również zwrócić modele Pydantic (więcej o tym później). + +Istnieje wiele innych obiektów i modeli, które zostaną automatycznie skonwertowane do formatu JSON (w tym ORM itp.). Spróbuj użyć swoich ulubionych, jest bardzo prawdopodobne, że są już obsługiwane. + +## Podsumowanie + +* Zaimportuj `FastAPI`. +* Stwórz instancję `app`. +* Dodaj **dekorator operacji na ścieżce** (taki jak `@app.get("/")`). +* Napisz **funkcję obsługującą ścieżkę** (taką jak `def root(): ...` powyżej). +* Uruchom serwer deweloperski (`uvicorn main:app --reload`). diff --git a/docs/pl/docs/tutorial/index.md b/docs/pl/docs/tutorial/index.md new file mode 100644 index 000000000..ed8752a95 --- /dev/null +++ b/docs/pl/docs/tutorial/index.md @@ -0,0 +1,80 @@ +# Samouczek - Wprowadzenie + +Ten samouczek pokaże Ci, krok po kroku, jak używać większości funkcji **FastAPI**. + +Każda część korzysta z poprzednich, ale jest jednocześnie osobnym tematem. Możesz przejść bezpośrednio do każdego rozdziału, jeśli szukasz rozwiązania konkretnego problemu. + +Samouczek jest tak zbudowany, żeby służył jako punkt odniesienia w przyszłości. + +Możesz wracać i sprawdzać dokładnie to czego potrzebujesz. + +## Wykonywanie kodu + +Wszystkie fragmenty kodu mogą być skopiowane bezpośrednio i użyte (są poprawnymi i przetestowanymi plikami). + +Żeby wykonać każdy przykład skopiuj kod to pliku `main.py` i uruchom `uvicorn` za pomocą: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +**BARDZO zalecamy** pisanie bądź kopiowanie kodu, edycję, a następnie wykonywanie go lokalnie. + +Użycie w Twoim edytorze jest tym, co pokazuje prawdziwe korzyści z FastAPI, pozwala zobaczyć jak mało kodu musisz napisać, wszystkie funkcje, takie jak kontrola typów, automatyczne uzupełnianie, itd. + +--- + +## Instalacja FastAPI + +Jako pierwszy krok zainstaluj FastAPI. + +Na potrzeby samouczka możesz zainstalować również wszystkie opcjonalne biblioteki: + +
+ +```console +$ pip install "fastapi[all]" + +---> 100% +``` + +
+ +...wliczając w to `uvicorn`, który będzie służył jako serwer wykonujacy Twój kod. + +!!! note + Możesz również wykonać instalację "krok po kroku". + + Prawdopodobnie zechcesz to zrobić, kiedy będziesz wdrażać swoją aplikację w środowisku produkcyjnym: + + ``` + pip install fastapi + ``` + + Zainstaluj też `uvicorn`, który będzie służył jako serwer: + + ``` + pip install "uvicorn[standard]" + ``` + + Tak samo możesz zainstalować wszystkie dodatkowe biblioteki, których chcesz użyć. + +## Zaawansowany poradnik + +Jest też **Zaawansowany poradnik**, który możesz przeczytać po lekturze tego **Samouczka**. + +**Zaawansowany poradnik** opiera się na tym samouczku, używa tych samych pojęć, żeby pokazać Ci kilka dodatkowych funkcji. + +Najpierw jednak powinieneś przeczytać **Samouczek** (czytasz go teraz). + +Ten rozdział jest zaprojektowany tak, że możesz stworzyć kompletną aplikację używając tylko informacji tutaj zawartych, a następnie rozszerzać ją na różne sposoby, w zależności od potrzeb, używając kilku dodatkowych pomysłów z **Zaawansowanego poradnika**. diff --git a/docs/pl/mkdocs.yml b/docs/pl/mkdocs.yml index 3c1351a12..1cd129420 100644 --- a/docs/pl/mkdocs.yml +++ b/docs/pl/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,18 +42,25 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ +- Samouczek: + - tutorial/index.md + - tutorial/first-steps.md markdown_extensions: - toc: permalink: true @@ -69,6 +78,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +108,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +122,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +132,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md index 6559b7398..61ee4f900 100644 --- a/docs/pt/docs/alternatives.md +++ b/docs/pt/docs/alternatives.md @@ -331,7 +331,7 @@ Agora APIStar é um conjunto de ferramentas para validar especificações OpenAP Existir. A idéia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos Python, que ao mesmo tempo fornecesse grande suporte ao editor, era algo que eu considerava uma brilhante idéia. - + E após procurar por um logo tempo por um framework similar e testar muitas alternativas diferentes, APIStar foi a melhor opção disponível. Então APIStar parou de existir como um servidor e Starlette foi criado, e foi uma nova melhor fundação para tal sistema. Essa foi a inspiração final para construir **FastAPI**. @@ -390,7 +390,7 @@ Essa é uma das principais coisas que **FastAPI** adiciona no topo, tudo baseado Controlar todas as partes web centrais. Adiciona recursos no topo. A classe `FastAPI` em si herda `Starlette`. - + Então, qualquer coisa que você faz com Starlette, você pode fazer diretamente com **FastAPI**, pois ele é basicamente um Starlette com esteróides. ### Uvicorn diff --git a/docs/pt/docs/async.md b/docs/pt/docs/async.md index 44f4b5148..be1278a1b 100644 --- a/docs/pt/docs/async.md +++ b/docs/pt/docs/async.md @@ -94,7 +94,7 @@ Para "síncrono" (contrário de "assíncrono") também é utilizado o termo "seq Essa idéia de código **assíncrono** descrito acima é algo às vezes chamado de **"concorrência"**. E é diferente de **"paralelismo"**. -**Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo". +**Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo". Mas os detalhes entre *concorrência* e *paralelismo* são bem diferentes. @@ -134,7 +134,7 @@ Mas então, embora você ainda não tenha os hambúrgueres, seu trabalho no caix Mas enquanto você se afasta do balcão e senta na mesa com o número da sua chamada, você pode trocar sua atenção para seu _crush_ :heart_eyes:, e "trabalhar" nisso. Então você está novamente fazendo algo muito "produtivo", como flertar com seu _crush_ :heart_eyes:. -Então o caixa diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porquê você tem o número de chamada, e os outros tem os números deles. +Então o caixa diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porquê você tem o número de chamada, e os outros tem os números deles. Então você espera que seu _crush_ :heart_eyes: termine a história que estava contando (terminar o trabalho atual / tarefa sendo processada), sorri gentilmente e diz que você está indo buscar os hambúrgueres. @@ -358,9 +358,9 @@ Tudo isso é o que deixa o FastAPI poderoso (através do Starlette) e que o faz !!! warning Você pode provavelmente pular isso. - + Esses são detalhes muito técnicos de como **FastAPI** funciona por baixo do capô. - + Se você tem algum conhecimento técnico (corrotinas, threads, blocking etc) e está curioso sobre como o FastAPI controla o `async def` vs normal `def`, vá em frente. ### Funções de operação de rota diff --git a/docs/pt/docs/benchmarks.md b/docs/pt/docs/benchmarks.md index 7f7c95ba1..07461ce46 100644 --- a/docs/pt/docs/benchmarks.md +++ b/docs/pt/docs/benchmarks.md @@ -2,7 +2,7 @@ As comparações independentes da TechEmpower mostram as aplicações **FastAPI** rodando com Uvicorn como um dos _frameworks_ Python mais rápidos disponíveis, somente atrás dos próprios Starlette e Uvicorn (utilizados internamente pelo FastAPI). (*) -Mas quando se checa _benchmarks_ e comparações você deveria ter o seguinte em mente. +Mas quando se checa _benchmarks_ e comparações você deveria ter o seguinte em mente. ## Comparações e velocidade diff --git a/docs/pt/docs/deployment.md b/docs/pt/docs/deployment.md index cd820cbd3..2272467fd 100644 --- a/docs/pt/docs/deployment.md +++ b/docs/pt/docs/deployment.md @@ -336,7 +336,7 @@ Você apenas precisa instalar um servidor ASGI compatível como:
```console - $ pip install uvicorn[standard] + $ pip install "uvicorn[standard]" ---> 100% ``` diff --git a/docs/pt/docs/deployment/deta.md b/docs/pt/docs/deployment/deta.md new file mode 100644 index 000000000..9271bba42 --- /dev/null +++ b/docs/pt/docs/deployment/deta.md @@ -0,0 +1,258 @@ +# Implantação FastAPI na Deta + +Nessa seção você aprenderá sobre como realizar a implantação de uma aplicação **FastAPI** na Deta utilizando o plano gratuito. 🎁 + +Isso tudo levará aproximadamente **10 minutos**. + +!!! info "Informação" + Deta é uma patrocinadora do **FastAPI**. 🎉 + +## Uma aplicação **FastAPI** simples + +* Crie e entre em um diretório para a sua aplicação, por exemplo, `./fastapideta/`. + +### Código FastAPI + +* Crie o arquivo `main.py` com: + +```Python +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int): + return {"item_id": item_id} +``` + +### Requisitos + +Agora, no mesmo diretório crie o arquivo `requirements.txt` com: + +```text +fastapi +``` + +!!! tip "Dica" + Você não precisa instalar Uvicorn para realizar a implantação na Deta, embora provavelmente queira instalá-lo para testar seu aplicativo localmente. + +### Estrutura de diretório + +Agora você terá o diretório `./fastapideta/` com dois arquivos: + +``` +. +└── main.py +└── requirements.txt +``` + +## Crie uma conta gratuita na Deta + +Agora crie uma conta gratuita na Deta, você precisará apenas de um email e senha. + +Você nem precisa de um cartão de crédito. + +## Instale a CLI + +Depois de ter sua conta criada, instale Deta CLI: + +=== "Linux, macOS" + +
+ + ```console + $ curl -fsSL https://get.deta.dev/cli.sh | sh + ``` + +
+ +=== "Windows PowerShell" + +
+ + ```console + $ iwr https://get.deta.dev/cli.ps1 -useb | iex + ``` + +
+ +Após a instalação, abra um novo terminal para que a CLI seja detectada. + +Em um novo terminal, confirme se foi instalado corretamente com: + +
+ +```console +$ deta --help + +Deta command line interface for managing deta micros. +Complete documentation available at https://docs.deta.sh + +Usage: + deta [flags] + deta [command] + +Available Commands: + auth Change auth settings for a deta micro + +... +``` + +
+ +!!! tip "Dica" + Se você tiver problemas ao instalar a CLI, verifique a documentação oficial da Deta. + +## Login pela CLI + +Agora faça login na Deta pela CLI com: + +
+ +```console +$ deta login + +Please, log in from the web page. Waiting.. +Logged in successfully. +``` + +
+ +Isso abrirá um navegador da Web e autenticará automaticamente. + +## Implantação com Deta + +Em seguida, implante seu aplicativo com a Deta CLI: + +
+ +```console +$ deta new + +Successfully created a new micro + +// Notice the "endpoint" 🔍 + +{ + "name": "fastapideta", + "runtime": "python3.7", + "endpoint": "https://qltnci.deta.dev", + "visor": "enabled", + "http_auth": "enabled" +} + +Adding dependencies... + + +---> 100% + + +Successfully installed fastapi-0.61.1 pydantic-1.7.2 starlette-0.13.6 +``` + +
+ +Você verá uma mensagem JSON semelhante a: + +```JSON hl_lines="4" +{ + "name": "fastapideta", + "runtime": "python3.7", + "endpoint": "https://qltnci.deta.dev", + "visor": "enabled", + "http_auth": "enabled" +} +``` + +!!! tip "Dica" + Sua implantação terá um URL `"endpoint"` diferente. + +## Confira + +Agora, abra seu navegador na URL do `endpoint`. No exemplo acima foi `https://qltnci.deta.dev`, mas o seu será diferente. + +Você verá a resposta JSON do seu aplicativo FastAPI: + +```JSON +{ + "Hello": "World" +} +``` + +Agora vá para o `/docs` da sua API, no exemplo acima seria `https://qltnci.deta.dev/docs`. + +Ele mostrará sua documentação como: + + + +## Permitir acesso público + +Por padrão, a Deta lidará com a autenticação usando cookies para sua conta. + +Mas quando estiver pronto, você pode torná-lo público com: + +
+ +```console +$ deta auth disable + +Successfully disabled http auth +``` + +
+ +Agora você pode compartilhar essa URL com qualquer pessoa e elas conseguirão acessar sua API. 🚀 + +## HTTPS + +Parabéns! Você realizou a implantação do seu app FastAPI na Deta! 🎉 🍰 + +Além disso, observe que a Deta lida corretamente com HTTPS para você, para que você não precise cuidar disso e tenha a certeza de que seus clientes terão uma conexão criptografada segura. ✅ 🔒 + +## Verifique o Visor + +Na UI da sua documentação (você estará em um URL como `https://qltnci.deta.dev/docs`) envie um request para *operação de rota* `/items/{item_id}`. + +Por exemplo com ID `5`. + +Agora vá para https://web.deta.sh. + +Você verá que há uma seção à esquerda chamada "Micros" com cada um dos seus apps. + +Você verá uma aba com "Detalhes", e também a aba "Visor", vá para "Visor". + +Lá você pode inspecionar as solicitações recentes enviadas ao seu aplicativo. + +Você também pode editá-los e reproduzi-los novamente. + + + +## Saiba mais + +Em algum momento, você provavelmente desejará armazenar alguns dados para seu aplicativo de uma forma que persista ao longo do tempo. Para isso você pode usar Deta Base, que também tem um generoso **nível gratuito**. + +Você também pode ler mais na documentação da Deta. + +## Conceitos de implantação + +Voltando aos conceitos que discutimos em [Deployments Concepts](./concepts.md){.internal-link target=_blank}, veja como cada um deles seria tratado com a Deta: + +* **HTTPS**: Realizado pela Deta, eles fornecerão um subdomínio e lidarão com HTTPS automaticamente. +* **Executando na inicialização**: Realizado pela Deta, como parte de seu serviço. +* **Reinicialização**: Realizado pela Deta, como parte de seu serviço. +* **Replicação**: Realizado pela Deta, como parte de seu serviço. +* **Memória**: Limite predefinido pela Deta, você pode contatá-los para aumentá-lo. +* **Etapas anteriores a inicialização**: Não suportado diretamente, você pode fazê-lo funcionar com o sistema Cron ou scripts adicionais. + +!!! note "Nota" + O Deta foi projetado para facilitar (e gratuitamente) a implantação rápida de aplicativos simples. + + Ele pode simplificar vários casos de uso, mas, ao mesmo tempo, não suporta outros, como o uso de bancos de dados externos (além do próprio sistema de banco de dados NoSQL da Deta), máquinas virtuais personalizadas, etc. + + Você pode ler mais detalhes na documentação da Deta para ver se é a escolha certa para você. diff --git a/docs/pt/docs/features.md b/docs/pt/docs/features.md index 20014fe2d..2b7836a6f 100644 --- a/docs/pt/docs/features.md +++ b/docs/pt/docs/features.md @@ -191,7 +191,7 @@ Com **FastAPI** você terá todos os recursos do **Pydantic** (já que FastAPI u * Vai bem com o/a seu/sua **IDE/linter/cérebro**: * Como as estruturas de dados do Pydantic são apenas instâncias de classes que você define, a auto completação, _linting_, _mypy_ e a sua intuição devem funcionar corretamente com seus dados validados. * **Rápido**: - * em _benchmarks_, o Pydantic é mais rápido que todas as outras bibliotecas testadas. + * em _benchmarks_, o Pydantic é mais rápido que todas as outras bibliotecas testadas. * Valida **estruturas complexas**: * Use modelos hierárquicos do Pydantic, `List` e `Dict` do `typing` do Python, etc. * Validadores permitem que esquemas de dados complexos sejam limpos e facilmente definidos, conferidos e documentados como JSON Schema. diff --git a/docs/pt/docs/help-fastapi.md b/docs/pt/docs/help-fastapi.md new file mode 100644 index 000000000..d82ce3414 --- /dev/null +++ b/docs/pt/docs/help-fastapi.md @@ -0,0 +1,148 @@ +# Ajuda FastAPI - Obter Ajuda + +Você gosta do **FastAPI**? + +Você gostaria de ajudar o FastAPI, outros usários, e o autor? + +Ou você gostaria de obter ajuda relacionada ao **FastAPI**?? + +Existem métodos muito simples de ajudar (A maioria das ajudas podem ser feitas com um ou dois cliques). + +E também existem vários modos de se conseguir ajuda. + +## Inscreva-se na newsletter + +Você pode se inscrever (pouco frequente) [**FastAPI e amigos** newsletter](/newsletter/){.internal-link target=_blank} para receber atualizações: + +* Notícias sobre FastAPI e amigos 🚀 +* Tutoriais 📝 +* Recursos ✨ +* Mudanças de última hora 🚨 +* Truques e dicas ✅ + +## Siga o FastAPI no twitter + +Siga @fastapi no **Twitter** para receber as últimas notícias sobre o **FastAPI**. 🐦 + +## Favorite o **FastAPI** no GitHub + +Você pode "favoritar" o FastAPI no GitHub (clicando na estrela no canto superior direito): https://github.com/tiangolo/fastapi. ⭐️ + +Favoritando, outros usuários poderão encontrar mais facilmente e verão que já foi útil para muita gente. + +## Acompanhe novos updates no repositorio do GitHub + +Você pode "acompanhar" (watch) o FastAPI no GitHub (clicando no botão com um "olho" no canto superior direito): https://github.com/tiangolo/fastapi. 👀 + +Podendo selecionar apenas "Novos Updates". + +Fazendo isto, serão enviadas notificações (em seu email) sempre que tiver novos updates (uma nova versão) com correções de bugs e novos recursos no **FastAPI** + +## Conect-se com o autor + +Você pode se conectar comigo (Sebastián Ramírez / `tiangolo`), o autor. + +Você pode: + +* Me siga no **GitHub**. + * Ver também outros projetos Open Source criados por mim que podem te ajudar. + * Me seguir para saber quando um novo projeto Open Source for criado. +* Me siga no **Twitter**. + * Me dizer o motivo pelo o qual você está usando o FastAPI(Adoro ouvir esse tipo de comentário). + * Saber quando eu soltar novos anúncios ou novas ferramentas. + * Também é possivel seguir o @fastapi no Twitter (uma conta aparte). +* Conect-se comigo no **Linkedin**. + * Saber quando eu fizer novos anúncios ou novas ferramentas (apesar de que uso o twitter com mais frequência 🤷‍♂). +* Ler meus artigos (ou me seguir) no **Dev.to** ou no **Medium**. + * Ficar por dentro de novas ideias, artigos, e ferramentas criadas por mim. + * Me siga para saber quando eu publicar algo novo. + +## Tweete sobre **FastAPI** + +Tweete sobre o **FastAPI** e compartilhe comigo e com os outros o porque de gostar do FastAPI. 🎉 + +Adoro ouvir sobre como o **FastAPI** é usado, o que você gosta nele, em qual projeto/empresa está sendo usado, etc. + +## Vote no FastAPI + +* Vote no **FastAPI** no Slant. +* Vote no **FastAPI** no AlternativeTo. + +## Responda perguntas no GitHub + +Você pode acompanhar as perguntas existentes e tentar ajudar outros, . 🤓 + +Ajudando a responder as questões de varias pessoas, você pode se tornar um [Expert em FastAPI](fastapi-people.md#experts){.internal-link target=_blank} oficial. 🎉 + +## Acompanhe o repositório do GitHub + +Você pode "acompanhar" (watch) o FastAPI no GitHub (clicando no "olho" no canto superior direito): https://github.com/tiangolo/fastapi. 👀 + +Se você selecionar "Acompanhando" (Watching) em vez de "Apenas Lançamentos" (Releases only) você receberá notificações quando alguém tiver uma nova pergunta. + +Assim podendo tentar ajudar a resolver essas questões. + +## Faça perguntas + +É possível criar uma nova pergunta no repositório do GitHub, por exemplo: + +* Faça uma **pergunta** ou pergunte sobre um **problema**. +* Sugira novos **recursos**. + +**Nota**: Se você fizer uma pergunta, então eu gostaria de pedir que você também ajude os outros com suas respectivas perguntas. 😉 + +## Crie um Pull Request + +É possível [contribuir](contributing.md){.internal-link target=_blank} no código fonte fazendo Pull Requests, por exemplo: + +* Para corrigir um erro de digitação que você encontrou na documentação. +* Para compartilhar um artigo, video, ou podcast criados por você sobre o FastAPI editando este arquivo. + * Não se esqueça de adicionar o link no começo da seção correspondente. +* Para ajudar [traduzir a documentação](contributing.md#translations){.internal-link target=_blank} para sua lingua. + * Também é possivel revisar as traduções já existentes. +* Para propor novas seções na documentação. +* Para corrigir um bug/questão. +* Para adicionar um novo recurso. + +## Entre no chat + +Entre no 👥 server de conversa do Discord 👥 e conheça novas pessoas da comunidade +do FastAPI. + +!!! dica + Para perguntas, pergunte nas questões do GitHub, lá tem um chance maior de você ser ajudado sobre o FastAPI [FastAPI Experts](fastapi-people.md#experts){.internal-link target=_blank}. + + Use o chat apenas para outro tipo de assunto. + +Também existe o chat do Gitter, porém ele não possuí canais e recursos avançados, conversas são mais engessadas, por isso o Discord é mais recomendado. + +### Não faça perguntas no chat + +Tenha em mente que os chats permitem uma "conversa mais livre", dessa forma é muito fácil fazer perguntas que são muito genéricas e dificeís de responder, assim você pode acabar não sendo respondido. + +Nas questões do GitHub o template irá te guiar para que você faça a sua pergunta de um jeito mais correto, fazendo com que você receba respostas mais completas, e até mesmo que você mesmo resolva o problema antes de perguntar. E no GitHub eu garanto que sempre irei responder todas as perguntas, mesmo que leve um tempo. Eu pessoalmente não consigo fazer isso via chat. 😅 + +Conversas no chat não são tão fáceis de serem encontrados quanto no GitHub, então questões e respostas podem se perder dentro da conversa. E apenas as que estão nas questões do GitHub contam para você se tornar um [Expert em FastAPI](fastapi-people.md#experts){.internal-link target=_blank}, então você receberá mais atenção nas questões do GitHub. + +Por outro lado, existem milhares de usuários no chat, então tem uma grande chance de você encontrar alguém para trocar uma idéia por lá em qualquer horário. 😄 + +## Patrocine o autor + +Você também pode ajudar o autor financeiramente (eu) através do GitHub sponsors. + +Lá você pode me pagar um cafézinho ☕️ como agradecimento. 😄 + +E você também pode se tornar um patrocinador Prata ou Ouro do FastAPI. 🏅🎉 + +## Patrocine as ferramente que potencializam o FastAPI + +Como você viu na documentação, o FastAPI se apoia em nos gigantes, Starlette e Pydantic. + +Patrocine também: + +* Samuel Colvin (Pydantic) +* Encode (Starlette, Uvicorn) + +--- + +Muito Obrigado! 🚀 diff --git a/docs/pt/docs/index.md b/docs/pt/docs/index.md index 848fff08a..51af486b9 100644 --- a/docs/pt/docs/index.md +++ b/docs/pt/docs/index.md @@ -124,7 +124,7 @@ Você também precisará de um servidor ASGI para produção, tal como ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -138,7 +138,7 @@ $ pip install uvicorn[standard] * Crie um arquivo `main.py` com: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -151,7 +151,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -161,7 +161,7 @@ def read_item(item_id: int, q: Optional[str] = None): Se seu código utiliza `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -174,7 +174,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -253,6 +253,8 @@ Agora modifique o arquivo `main.py` para receber um corpo para uma requisição Declare o corpo utilizando tipos padrão Python, graças ao Pydantic. ```Python hl_lines="4 9-12 25-27" +from typing import Union + from fastapi import FastAPI from pydantic import BaseModel @@ -262,7 +264,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool] = None @app.get("/") @@ -271,7 +273,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -365,7 +367,7 @@ Voltando ao código do exemplo anterior, **FastAPI** irá: * 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`). * Para requisições `PUT` para `/items/{item_id}`, lerá o corpo como JSON e: - * Verifica que tem um atributo obrigatório `name` que deve ser `str`. + * 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. @@ -434,7 +436,6 @@ Usados por Pydantic: Usados por Starlette: * requests - Necessário se você quiser utilizar o `TestClient`. -* aiofiles - Necessário se você quiser utilizar o `FileResponse` ou `StaticFiles`. * jinja2 - Necessário se você quiser utilizar a configuração padrão de templates. * python-multipart - Necessário se você quiser suporte com "parsing" de formulário, com `request.form()`. * itsdangerous - Necessário para suporte a `SessionMiddleware`. diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md index df70afd40..9f12211c7 100644 --- a/docs/pt/docs/python-types.md +++ b/docs/pt/docs/python-types.md @@ -313,4 +313,3 @@ O importante é que, usando tipos padrão de Python, em um único local (em vez !!! info "Informação" Se você já passou por todo o tutorial e voltou para ver mais sobre os tipos, um bom recurso é a "cheat sheet" do `mypy` . - diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md new file mode 100644 index 000000000..625fa2b11 --- /dev/null +++ b/docs/pt/docs/tutorial/background-tasks.md @@ -0,0 +1,94 @@ +# Tarefas em segundo plano + +Você pode definir tarefas em segundo plano a serem executadas _ após _ retornar uma resposta. + +Isso é útil para operações que precisam acontecer após uma solicitação, mas que o cliente realmente não precisa esperar a operação ser concluída para receber a resposta. + +Isso inclui, por exemplo: + +- Envio de notificações por email após a realização de uma ação: + - Como conectar-se a um servidor de e-mail e enviar um e-mail tende a ser "lento" (vários segundos), você pode retornar a resposta imediatamente e enviar a notificação por e-mail em segundo plano. +- Processando dados: + - Por exemplo, digamos que você receba um arquivo que deve passar por um processo lento, você pode retornar uma resposta de "Aceito" (HTTP 202) e processá-lo em segundo plano. + +## Usando `BackgroundTasks` + +Primeiro, importe `BackgroundTasks` e defina um parâmetro em sua _função de operação de caminho_ com uma declaração de tipo de `BackgroundTasks`: + +```Python hl_lines="1 13" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +O **FastAPI** criará o objeto do tipo `BackgroundTasks` para você e o passará como esse parâmetro. + +## Criar uma função de tarefa + +Crie uma função a ser executada como tarefa em segundo plano. + +É apenas uma função padrão que pode receber parâmetros. + +Pode ser uma função `async def` ou `def` normal, o **FastAPI** saberá como lidar com isso corretamente. + +Nesse caso, a função de tarefa gravará em um arquivo (simulando o envio de um e-mail). + +E como a operação de gravação não usa `async` e `await`, definimos a função com `def` normal: + +```Python hl_lines="6-9" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +## Adicionar a tarefa em segundo plano + +Dentro de sua _função de operação de caminho_, passe sua função de tarefa para o objeto _tarefas em segundo plano_ com o método `.add_task()`: + +```Python hl_lines="14" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +`.add_task()` recebe como argumentos: + +- Uma função de tarefa a ser executada em segundo plano (`write_notification`). +- Qualquer sequência de argumentos que deve ser passada para a função de tarefa na ordem (`email`). +- Quaisquer argumentos nomeados que devem ser passados ​​para a função de tarefa (`mensagem = "alguma notificação"`). + +## Injeção de dependência + +Usar `BackgroundTasks` também funciona com o sistema de injeção de dependência, você pode declarar um parâmetro do tipo `BackgroundTasks` em vários níveis: em uma _função de operação de caminho_, em uma dependência (confiável), em uma subdependência, etc. + +O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de forma que todas as tarefas em segundo plano sejam mescladas e executadas em segundo plano posteriormente: + +```Python hl_lines="13 15 22 25" +{!../../../docs_src/background_tasks/tutorial002.py!} +``` + +Neste exemplo, as mensagens serão gravadas no arquivo `log.txt` _após_ o envio da resposta. + +Se houver uma consulta na solicitação, ela será gravada no log em uma tarefa em segundo plano. + +E então outra tarefa em segundo plano gerada na _função de operação de caminho_ escreverá uma mensagem usando o parâmetro de caminho `email`. + +## Detalhes técnicos + +A classe `BackgroundTasks` vem diretamente de `starlette.background`. + +Ela é importada/incluída diretamente no FastAPI para que você possa importá-la do `fastapi` e evitar a importação acidental da alternativa `BackgroundTask` (sem o `s` no final) de `starlette.background`. + +Usando apenas `BackgroundTasks` (e não `BackgroundTask`), é então possível usá-la como um parâmetro de _função de operação de caminho_ e deixar o **FastAPI** cuidar do resto para você, assim como ao usar o objeto `Request` diretamente. + +Ainda é possível usar `BackgroundTask` sozinho no FastAPI, mas você deve criar o objeto em seu código e retornar uma Starlette `Response` incluindo-o. + +Você pode ver mais detalhes na documentação oficiais da Starlette para tarefas em segundo plano . + +## Ressalva + +Se você precisa realizar cálculos pesados ​​em segundo plano e não necessariamente precisa que seja executado pelo mesmo processo (por exemplo, você não precisa compartilhar memória, variáveis, etc), você pode se beneficiar do uso de outras ferramentas maiores, como Celery . + +Eles tendem a exigir configurações mais complexas, um gerenciador de fila de mensagens/tarefas, como RabbitMQ ou Redis, mas permitem que você execute tarefas em segundo plano em vários processos e, especialmente, em vários servidores. + +Para ver um exemplo, verifique os [Geradores de projeto](../project-generation.md){.internal-link target=\_blank}, todos incluem celery já configurado. + +Mas se você precisa acessar variáveis ​​e objetos do mesmo aplicativo **FastAPI**, ou precisa realizar pequenas tarefas em segundo plano (como enviar uma notificação por e-mail), você pode simplesmente usar `BackgroundTasks`. + +## Recapitulando + +Importe e use `BackgroundTasks` com parâmetros em _funções de operação de caminho_ e dependências para adicionar tarefas em segundo plano. diff --git a/docs/pt/docs/tutorial/body.md b/docs/pt/docs/tutorial/body.md new file mode 100644 index 000000000..99e05ab77 --- /dev/null +++ b/docs/pt/docs/tutorial/body.md @@ -0,0 +1,165 @@ +# Corpo da Requisição + +Quando você precisa enviar dados de um cliente (como de um navegador web) para sua API, você o envia como um **corpo da requisição**. + +O corpo da **requisição** é a informação enviada pelo cliente para sua API. O corpo da **resposta** é a informação que sua API envia para o cliente. + +Sua API quase sempre irá enviar um corpo na **resposta**. Mas os clientes não necessariamente precisam enviar um corpo em toda **requisição**. + +Para declarar um corpo da **requisição**, você utiliza os modelos do Pydantic com todos os seus poderes e benefícios. + +!!! info "Informação" + Para enviar dados, você deve usar utilizar um dos métodos: `POST` (Mais comum), `PUT`, `DELETE` ou `PATCH`. + + Enviar um corpo em uma requisição `GET` não tem um comportamento definido nas especificações, porém é suportado pelo FastAPI, apenas para casos de uso bem complexos/extremos. + + Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição para um `GET`, e proxies que intermediarem podem não suportar o corpo da requisição. + +## Importe o `BaseModel` do Pydantic + +Primeiro, você precisa importar `BaseModel` do `pydantic`: + +```Python hl_lines="4" +{!../../../docs_src/body/tutorial001.py!} +``` + +## Crie seu modelo de dados + +Então você declara seu modelo de dados como uma classe que herda `BaseModel`. + +Utilize os tipos Python padrão para todos os atributos: + +```Python hl_lines="7-11" +{!../../../docs_src/body/tutorial001.py!} +``` + +Assim como quando declaramos parâmetros de consulta, quando um atributo do modelo possui um valor padrão, ele se torna opcional. Caso contrário, se torna obrigatório. Use `None` para torná-lo opcional. + +Por exemplo, o modelo acima declara um JSON "`object`" (ou `dict` no Python) como esse: + +```JSON +{ + "name": "Foo", + "description": "Uma descrição opcional", + "price": 45.2, + "tax": 3.5 +} +``` + +...como `description` e `tax` são opcionais (Com um valor padrão de `None`), esse JSON "`object`" também é válido: + +```JSON +{ + "name": "Foo", + "price": 45.2 +} +``` + +## Declare como um parâmetro + +Para adicionar o corpo na *função de operação de rota*, declare-o da mesma maneira que você declarou parâmetros de rota e consulta: + +```Python hl_lines="18" +{!../../../docs_src/body/tutorial001.py!} +``` + +...E declare o tipo como o modelo que você criou, `Item`. + +## Resultados + +Apenas com esse declaração de tipos do Python, o **FastAPI** irá: + +* Ler o corpo da requisição como um JSON. +* Converter os tipos correspondentes (se necessário). +* Validar os dados. + * Se algum dados for inválido, irá retornar um erro bem claro, indicando exatamente onde e o que está incorreto. +* Entregar a você a informação recebida no parâmetro `item`. + * Como você o declarou na função como do tipo `Item`, você também terá o suporte do editor (completação, etc) para todos os atributos e seus tipos. +* Gerar um Esquema JSON com as definições do seu modelo, você também pode utilizá-lo em qualquer lugar que quiser, se fizer sentido para seu projeto. +* Esses esquemas farão parte do esquema OpenAPI, e utilizados nas UIs de documentação automática. + +## Documentação automática + +Os esquemas JSON dos seus modelos farão parte do esquema OpenAPI gerado para sua aplicação, e aparecerão na documentação interativa da API: + + + +E também serão utilizados em cada *função de operação de rota* que utilizá-los: + + + +## Suporte do editor de texto: + +No seu editor de texto, dentro da função você receberá dicas de tipos e completação em todo lugar (isso não aconteceria se você recebesse um `dict` em vez de um modelo Pydantic): + + + +Você também poderá receber verificações de erros para operações de tipos incorretas: + + + +Isso não é por acaso, todo o framework foi construído em volta deste design. + +E foi imensamente testado na fase de design, antes de qualquer implementação, para garantir que funcionaria para todos os editores de texto. + +Houveram mudanças no próprio Pydantic para que isso fosse possível. + +As capturas de tela anteriores foram capturas no Visual Studio Code. + +Mas você terá o mesmo suporte do editor no PyCharm e na maioria dos editores Python: + + + +!!! tip "Dica" + Se você utiliza o PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm . + + Melhora o suporte do editor para seus modelos Pydantic com:: + + * completação automática + * verificação de tipos + * refatoração + * buscas + * inspeções + +## Use o modelo + +Dentro da função, você pode acessar todos os atributos do objeto do modelo diretamente: + +```Python hl_lines="21" +{!../../../docs_src/body/tutorial002.py!} +``` + +## Corpo da requisição + parâmetros de rota + +Você pode declarar parâmetros de rota e corpo da requisição ao mesmo tempo. + +O **FastAPI** irá reconhecer que os parâmetros da função que combinam com parâmetros de rota devem ser **retirados da rota**, e parâmetros da função que são declarados como modelos Pydantic sejam **retirados do corpo da requisição**. + +```Python hl_lines="17-18" +{!../../../docs_src/body/tutorial003.py!} +``` + +## Corpo da requisição + parâmetros de rota + parâmetros de consulta + +Você também pode declarar parâmetros de **corpo**, **rota** e **consulta**, ao mesmo tempo. + +O **FastAPI** irá reconhecer cada um deles e retirar a informação do local correto. + +```Python hl_lines="18" +{!../../../docs_src/body/tutorial004.py!} +``` + +Os parâmetros da função serão reconhecidos conforme abaixo: + +* Se o parâmetro também é declarado na **rota**, será utilizado como um parâmetro de rota. +* Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**. +* Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição. + +!!! note "Observação" + O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`. + + O `Union` em `Union[str, None]` não é utilizado pelo FastAPI, mas permite ao seu editor de texto lhe dar um suporte melhor e detectar erros. + +## Sem o Pydantic + +Se você não quer utilizar os modelos Pydantic, você também pode utilizar o parâmetro **Body**. Veja a documentação para [Body - Parâmetros múltiplos: Valores singulares no body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. diff --git a/docs/pt/docs/tutorial/cookie-params.md b/docs/pt/docs/tutorial/cookie-params.md new file mode 100644 index 000000000..1a60e3571 --- /dev/null +++ b/docs/pt/docs/tutorial/cookie-params.md @@ -0,0 +1,33 @@ +# Parâmetros de Cookie + +Você pode definir parâmetros de Cookie da mesma maneira que define paramêtros com `Query` e `Path`. + +## Importe `Cookie` + +Primeiro importe `Cookie`: + +```Python hl_lines="3" +{!../../../docs_src/cookie_params/tutorial001.py!} +``` + +## Declare parâmetros de `Cookie` + +Então declare os paramêtros de cookie usando a mesma estrutura que em `Path` e `Query`. + +O primeiro valor é o valor padrão, você pode passar todas as validações adicionais ou parâmetros de anotação: + +```Python hl_lines="9" +{!../../../docs_src/cookie_params/tutorial001.py!} +``` + +!!! note "Detalhes Técnicos" + `Cookie` é uma classe "irmã" de `Path` e `Query`. Ela também herda da mesma classe em comum `Param`. + + Mas lembre-se que quando você importa `Query`, `Path`, `Cookie` e outras de `fastapi`, elas são na verdade funções que retornam classes especiais. + +!!! info "Informação" + Para declarar cookies, você precisa usar `Cookie`, caso contrário, os parâmetros seriam interpretados como parâmetros de consulta. + +## Recapitulando + +Declare cookies com `Cookie`, usando o mesmo padrão comum que utiliza-se em `Query` e `Path`. diff --git a/docs/pt/docs/tutorial/extra-data-types.md b/docs/pt/docs/tutorial/extra-data-types.md new file mode 100644 index 000000000..e4b9913dc --- /dev/null +++ b/docs/pt/docs/tutorial/extra-data-types.md @@ -0,0 +1,66 @@ +# Tipos de dados extras + +Até agora, você tem usado tipos de dados comuns, tais como: + +* `int` +* `float` +* `str` +* `bool` + +Mas você também pode usar tipos de dados mais complexos. + +E você ainda terá os mesmos recursos que viu até agora: + +* Ótimo suporte do editor. +* Conversão de dados das requisições recebidas. +* Conversão de dados para os dados da resposta. +* Validação de dados. +* Anotação e documentação automáticas. + +## Outros tipos de dados + +Aqui estão alguns dos tipos de dados adicionais que você pode usar: + +* `UUID`: + * Um "Identificador Universalmente Único" padrão, comumente usado como ID em muitos bancos de dados e sistemas. + * Em requisições e respostas será representado como uma `str`. +* `datetime.datetime`: + * O `datetime.datetime` do Python. + * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `2008-09-15T15:53:00+05:00`. +* `datetime.date`: + * O `datetime.date` do Python. + * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `2008-09-15`. +* `datetime.time`: + * O `datetime.time` do Python. + * Em requisições e respostas será representado como uma `str` no formato ISO 8601, exemplo: `14:23:55.003`. +* `datetime.timedelta`: + * O `datetime.timedelta` do Python. + * Em requisições e respostas será representado como um `float` de segundos totais. + * O Pydantic também permite representá-lo como uma "codificação ISO 8601 diferença de tempo", cheque a documentação para mais informações. +* `frozenset`: + * Em requisições e respostas, será tratado da mesma forma que um `set`: + * Nas requisições, uma lista será lida, eliminando duplicadas e convertendo-a em um `set`. + * Nas respostas, o `set` será convertido para uma `list`. + * O esquema gerado vai especificar que os valores do `set` são unicos (usando o `uniqueItems` do JSON Schema). +* `bytes`: + * O `bytes` padrão do Python. + * Em requisições e respostas será representado como uma `str`. + * O esquema gerado vai especificar que é uma `str` com o "formato" `binary`. +* `Decimal`: + * O `Decimal` padrão do Python. + * Em requisições e respostas será representado como um `float`. +* Você pode checar todos os tipos de dados válidos do Pydantic aqui: Tipos de dados do Pydantic. + +## Exemplo + +Aqui está um exemplo de *operação de rota* com parâmetros utilizando-se de alguns dos tipos acima. + +```Python hl_lines="1 3 12-16" +{!../../../docs_src/extra_data_types/tutorial001.py!} +``` + +Note que os parâmetros dentro da função tem seu tipo de dados natural, e você pode, por exemplo, realizar manipulações normais de data, como: + +```Python hl_lines="18-19" +{!../../../docs_src/extra_data_types/tutorial001.py!} +``` diff --git a/docs/pt/docs/tutorial/handling-errors.md b/docs/pt/docs/tutorial/handling-errors.md new file mode 100644 index 000000000..97a2e3eac --- /dev/null +++ b/docs/pt/docs/tutorial/handling-errors.md @@ -0,0 +1,251 @@ +# Manipulação de erros + +Há diversas situações em que você precisa notificar um erro a um cliente que está utilizando a sua API. + +Esse cliente pode ser um browser com um frontend, o código de outra pessoa, um dispositivo IoT, etc. + +Pode ser que você precise comunicar ao cliente que: + +* O cliente não tem direitos para realizar aquela operação. +* O cliente não tem acesso aquele recurso. +* O item que o cliente está tentando acessar não existe. +* etc. + + +Nesses casos, você normalmente retornaria um **HTTP status code** próximo ao status code na faixa do status code **400** (do 400 ao 499). + +Isso é bastante similar ao caso do HTTP status code 200 (do 200 ao 299). Esses "200" status codes significam que, de algum modo, houve sucesso na requisição. + +Os status codes na faixa dos 400 significam que houve um erro por parte do cliente. + +Você se lembra de todos aqueles erros (e piadas) a respeito do "**404 Not Found**"? + +## Use o `HTTPException` + +Para retornar ao cliente *responses* HTTP com erros, use o `HTTPException`. + +### Import `HTTPException` + +```Python hl_lines="1" +{!../../../docs_src/handling_errors/tutorial001.py!} +``` + +### Lance o `HTTPException` no seu código. + +`HTTPException`, ao fundo, nada mais é do que a conjunção entre uma exceção comum do Python e informações adicionais relevantes para APIs. + +E porque é uma exceção do Python, você não **retorna** (return) o `HTTPException`, você lança o (raise) no seu código. + +Isso também significa que, se você está escrevendo uma função de utilidade, a qual você está chamando dentro da sua função de operações de caminhos, e você lança o `HTTPException` dentro da função de utilidade, o resto do seu código não será executado dentro da função de operações de caminhos. Ao contrário, o `HTTPException` irá finalizar a requisição no mesmo instante e enviará o erro HTTP oriundo do `HTTPException` para o cliente. + +O benefício de lançar uma exceção em vez de retornar um valor ficará mais evidente na seção sobre Dependências e Segurança. + +Neste exemplo, quando o cliente pede, na requisição, por um item cujo ID não existe, a exceção com o status code `404` é lançada: + +```Python hl_lines="11" +{!../../../docs_src/handling_errors/tutorial001.py!} +``` + +### A response resultante + + +Se o cliente faz uma requisição para `http://example.com/items/foo` (um `item_id` `"foo"`), esse cliente receberá um HTTP status code 200, e uma resposta JSON: + + +``` +{ + "item": "The Foo Wrestlers" +} +``` + +Mas se o cliente faz uma requisição para `http://example.com/items/bar` (ou seja, um não existente `item_id "bar"`), esse cliente receberá um HTTP status code 404 (o erro "não encontrado" — *not found error*), e uma resposta JSON: + +```JSON +{ + "detail": "Item not found" +} +``` + +!!! tip "Dica" + Quando você lançar um `HTTPException`, você pode passar qualquer valor convertível em JSON como parâmetro de `detail`, e não apenas `str`. + + Você pode passar um `dict` ou um `list`, etc. + Esses tipos de dados são manipulados automaticamente pelo **FastAPI** e convertidos em JSON. + + +## Adicione headers customizados + +Há certas situações em que é bastante útil poder adicionar headers customizados no HTTP error. Exemplo disso seria adicionar headers customizados para tipos de segurança. + +Você provavelmente não precisará utilizar esses headers diretamente no seu código. + +Mas caso você precise, para um cenário mais complexo, você pode adicionar headers customizados: + +```Python hl_lines="14" +{!../../../docs_src/handling_errors/tutorial002.py!} +``` + +## Instalando manipuladores de exceções customizados + +Você pode adicionar manipuladores de exceção customizados com a mesma seção de utilidade de exceções presentes no Starlette + +Digamos que você tenha uma exceção customizada `UnicornException` que você (ou uma biblioteca que você use) precise lançar (`raise`). + +Nesse cenário, se você precisa manipular essa exceção de modo global com o FastAPI, você pode adicionar um manipulador de exceção customizada com `@app.exception_handler()`. + +```Python hl_lines="5-7 13-18 24" +{!../../../docs_src/handling_errors/tutorial003.py!} +``` + +Nesse cenário, se você fizer uma requisição para `/unicorns/yolo`, a *operação de caminho* vai lançar (`raise`) o `UnicornException`. + +Essa exceção será manipulada, contudo, pelo `unicorn_exception_handler`. + +Dessa forma você receberá um erro "limpo", com o HTTP status code `418` e um JSON com o conteúdo: + +```JSON +{"message": "Oops! yolo did something. There goes a rainbow..."} +``` + +!!! note "Detalhes Técnicos" + Você também pode usar `from starlette.requests import Request` and `from starlette.responses import JSONResponse`. + + **FastAPI** disponibiliza o mesmo `starlette.responses` através do `fastapi.responses` por conveniência ao desenvolvedor. Contudo, a maior parte das respostas disponíveis vem diretamente do Starlette. O mesmo acontece com o `Request`. + +## Sobrescreva o manipulador padrão de exceções + +**FastAPI** tem alguns manipuladores padrão de exceções. + +Esses manipuladores são os responsáveis por retornar o JSON padrão de respostas quando você lança (`raise`) o `HTTPException` e quando a requisição tem dados invalidos. + +Você pode sobrescrever esses manipuladores de exceção com os seus próprios manipuladores. + +## Sobrescreva exceções de validação da requisição + +Quando a requisição contém dados inválidos, **FastAPI** internamente lança para o `RequestValidationError`. + +Para sobrescrevê-lo, importe o `RequestValidationError` e use-o com o `@app.exception_handler(RequestValidationError)` para decorar o manipulador de exceções. + +```Python hl_lines="2 14-16" +{!../../../docs_src/handling_errors/tutorial004.py!} +``` + +Se você for ao `/items/foo`, em vez de receber o JSON padrão com o erro: + +```JSON +{ + "detail": [ + { + "loc": [ + "path", + "item_id" + ], + "msg": "value is not a valid integer", + "type": "type_error.integer" + } + ] +} +``` + +você receberá a versão em texto: + +``` +1 validation error +path -> item_id + value is not a valid integer (type=type_error.integer) +``` + +### `RequestValidationError` vs `ValidationError` + +!!! warning "Aviso" + Você pode pular estes detalhes técnicos caso eles não sejam importantes para você neste momento. + +`RequestValidationError` é uma subclasse do `ValidationError` existente no Pydantic. + +**FastAPI** faz uso dele para que você veja o erro no seu log, caso você utilize um modelo de Pydantic em `response_model`, e seus dados tenham erro. + +Contudo, o cliente ou usuário não terão acesso a ele. Ao contrário, o cliente receberá um "Internal Server Error" com o HTTP status code `500`. + +E assim deve ser porque seria um bug no seu código ter o `ValidationError` do Pydantic na sua *response*, ou em qualquer outro lugar do seu código (que não na requisição do cliente). + +E enquanto você conserta o bug, os clientes / usuários não deveriam ter acesso às informações internas do erro, porque, desse modo, haveria exposição de uma vulnerabilidade de segurança. + +Do mesmo modo, você pode sobreescrever o `HTTPException`. + +Por exemplo, você pode querer retornar uma *response* em *plain text* ao invés de um JSON para os seguintes erros: + +```Python hl_lines="3-4 9-11 22" +{!../../../docs_src/handling_errors/tutorial004.py!} +``` + +!!! note "Detalhes Técnicos" + Você pode usar `from starlette.responses import PlainTextResponse`. + + **FastAPI** disponibiliza o mesmo `starlette.responses` como `fastapi.responses`, como conveniência a você, desenvolvedor. Contudo, a maior parte das respostas disponíveis vem diretamente do Starlette. + + +### Use o body do `RequestValidationError`. + +O `RequestValidationError` contém o `body` que ele recebeu de dados inválidos. + +Você pode utilizá-lo enquanto desenvolve seu app para conectar o *body* e debugá-lo, e assim retorná-lo ao usuário, etc. + +Tente enviar um item inválido como este: + +```JSON +{ + "title": "towel", + "size": "XL" +} +``` + +Você receberá uma *response* informando-o de que a data é inválida, e contendo o *body* recebido: + +```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" + } +} +``` + +#### O `HTTPException` do FastAPI vs o `HTTPException` do Starlette. + +O **FastAPI** tem o seu próprio `HTTPException`. + +E a classe de erro `HTTPException` do **FastAPI** herda da classe de erro do `HTTPException` do Starlette. + +A diferença entre os dois é a de que o `HTTPException` do **FastAPI** permite que você adicione *headers* que serão incluídos nas *responses*. + +Esses *headers* são necessários/utilizados internamente pelo OAuth 2.0 e também por outras utilidades de segurança. + +Portanto, você pode continuar lançando o `HTTPException` do **FastAPI** normalmente no seu código. + +Porém, quando você registrar um manipulador de exceção, você deve registrá-lo através do `HTTPException` do Starlette. + +Dessa forma, se qualquer parte do código interno, extensão ou plug-in do Starlette lançar o `HTTPException`, o seu manipulador de exceção poderá capturar esse lançamento e tratá-lo. + +```Python +from starlette.exceptions import HTTPException as StarletteHTTPException +``` + +### Re-use os manipulares de exceção do **FastAPI** + +Se você quer usar a exceção em conjunto com o mesmo manipulador de exceção *default* do **FastAPI**, você pode importar e re-usar esses manipuladores de exceção do `fastapi.exception_handlers`: + +```Python hl_lines="2-5 15 21" +{!../../../docs_src/handling_errors/tutorial006.py!} +``` + +Nesse exemplo você apenas imprime (`print`) o erro com uma mensagem expressiva. Mesmo assim, dá para pegar a ideia. Você pode usar a exceção e então apenas re-usar o manipulador de exceção *default*. diff --git a/docs/pt/docs/tutorial/header-params.md b/docs/pt/docs/tutorial/header-params.md new file mode 100644 index 000000000..94ee784cd --- /dev/null +++ b/docs/pt/docs/tutorial/header-params.md @@ -0,0 +1,128 @@ +# Parâmetros de Cabeçalho + +Você pode definir parâmetros de Cabeçalho da mesma maneira que define paramêtros com `Query`, `Path` e `Cookie`. + +## importe `Header` + +Primeiro importe `Header`: + +=== "Python 3.6 and above" + + ```Python hl_lines="3" + {!> ../../../docs_src/header_params/tutorial001.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="1" + {!> ../../../docs_src/header_params/tutorial001_py310.py!} + ``` + +## Declare parâmetros de `Header` + +Então declare os paramêtros de cabeçalho usando a mesma estrutura que em `Path`, `Query` e `Cookie`. + +O primeiro valor é o valor padrão, você pode passar todas as validações adicionais ou parâmetros de anotação: + +=== "Python 3.6 and above" + + ```Python hl_lines="9" + {!> ../../../docs_src/header_params/tutorial001.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="7" + {!> ../../../docs_src/header_params/tutorial001_py310.py!} + ``` + +!!! note "Detalhes Técnicos" + `Header` é uma classe "irmã" de `Path`, `Query` e `Cookie`. Ela também herda da mesma classe em comum `Param`. + + Mas lembre-se que quando você importa `Query`, `Path`, `Header`, e outras de `fastapi`, elas são na verdade funções que retornam classes especiais. + +!!! info + Para declarar headers, você precisa usar `Header`, caso contrário, os parâmetros seriam interpretados como parâmetros de consulta. + +## Conversão automática + +`Header` tem algumas funcionalidades a mais em relação a `Path`, `Query` e `Cookie`. + +A maioria dos cabeçalhos padrão são separados pelo caractere "hífen", também conhecido como "sinal de menos" (`-`). + +Mas uma variável como `user-agent` é inválida em Python. + +Portanto, por padrão, `Header` converterá os caracteres de nomes de parâmetros de sublinhado (`_`) para hífen (`-`) para extrair e documentar os cabeçalhos. + +Além disso, os cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, portanto, você pode declará-los com o estilo padrão do Python (também conhecido como "snake_case"). + +Portanto, você pode usar `user_agent` como faria normalmente no código Python, em vez de precisar colocar as primeiras letras em maiúsculas como `User_Agent` ou algo semelhante. + +Se por algum motivo você precisar desabilitar a conversão automática de sublinhados para hífens, defina o parâmetro `convert_underscores` de `Header` para `False`: + +=== "Python 3.6 and above" + + ```Python hl_lines="10" + {!> ../../../docs_src/header_params/tutorial002.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="8" + {!> ../../../docs_src/header_params/tutorial002_py310.py!} + ``` + +!!! warning "Aviso" + Antes de definir `convert_underscores` como `False`, lembre-se de que alguns proxies e servidores HTTP não permitem o uso de cabeçalhos com sublinhados. + +## Cabeçalhos duplicados + +É possível receber cabeçalhos duplicados. Isso significa, o mesmo cabeçalho com vários valores. + +Você pode definir esses casos usando uma lista na declaração de tipo. + +Você receberá todos os valores do cabeçalho duplicado como uma `list` Python. + +Por exemplo, para declarar um cabeçalho de `X-Token` que pode aparecer mais de uma vez, você pode escrever: + +=== "Python 3.6 and above" + + ```Python hl_lines="9" + {!> ../../../docs_src/header_params/tutorial003.py!} + ``` + +=== "Python 3.9 and above" + + ```Python hl_lines="9" + {!> ../../../docs_src/header_params/tutorial003_py39.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="7" + {!> ../../../docs_src/header_params/tutorial003_py310.py!} + ``` + +Se você se comunicar com essa *operação de caminho* enviando dois cabeçalhos HTTP como: + +``` +X-Token: foo +X-Token: bar +``` + +A resposta seria como: + +```JSON +{ + "X-Token values": [ + "bar", + "foo" + ] +} +``` + +## Recapitulando + +Declare cabeçalhos com `Header`, usando o mesmo padrão comum que utiliza-se em `Query`, `Path` e `Cookie`. + +E não se preocupe com sublinhados em suas variáveis, FastAPI cuidará da conversão deles. diff --git a/docs/pt/docs/tutorial/index.md b/docs/pt/docs/tutorial/index.md index f93fd8d75..b1abd32bc 100644 --- a/docs/pt/docs/tutorial/index.md +++ b/docs/pt/docs/tutorial/index.md @@ -43,7 +43,7 @@ Para o tutorial, você deve querer instalá-lo com todas as dependências e recu
```console -$ pip install fastapi[all] +$ pip install "fastapi[all]" ---> 100% ``` @@ -64,7 +64,7 @@ $ pip install fastapi[all] Também instale o `uvicorn` para funcionar como servidor: ``` - pip install uvicorn[standard] + pip install "uvicorn[standard]" ``` E o mesmo para cada dependência opcional que você quiser usar. diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md index 20913a564..5de3756ed 100644 --- a/docs/pt/docs/tutorial/path-params.md +++ b/docs/pt/docs/tutorial/path-params.md @@ -72,7 +72,7 @@ O mesmo erro apareceria se você tivesse fornecido um `float` ao invés de um `i ## Documentação -Quando você abrir o seu navegador em http://127.0.0.1:8000/docs, você verá de forma automática e interativa a documtação da API como: +Quando você abrir o seu navegador em http://127.0.0.1:8000/docs, você verá de forma automática e interativa a documentação da API como: diff --git a/docs/pt/docs/tutorial/query-params-str-validations.md b/docs/pt/docs/tutorial/query-params-str-validations.md index baac5f493..9a9e071db 100644 --- a/docs/pt/docs/tutorial/query-params-str-validations.md +++ b/docs/pt/docs/tutorial/query-params-str-validations.md @@ -8,12 +8,12 @@ Vamos utilizar essa aplicação como exemplo: {!../../../docs_src/query_params_str_validations/tutorial001.py!} ``` -O parâmetro de consulta `q` é do tipo `Optional[str]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório. +O parâmetro de consulta `q` é do tipo `Union[str, None]`, o que significa que é do tipo `str` mas que também pode ser `None`, e de fato, o valor padrão é `None`, então o FastAPI saberá que não é obrigatório. !!! note "Observação" O FastAPI saberá que o valor de `q` não é obrigatório por causa do valor padrão `= None`. - O `Optional` em `Optional[str]` não é usado pelo FastAPI, mas permitirá que seu editor lhe dê um melhor suporte e detecte erros. + O `Union` em `Union[str, None]` não é usado pelo FastAPI, mas permitirá que seu editor lhe dê um melhor suporte e detecte erros. ## Validação adicional @@ -35,18 +35,18 @@ Agora utilize-o como valor padrão do seu parâmetro, definindo o parâmetro `ma {!../../../docs_src/query_params_str_validations/tutorial002.py!} ``` -Note que substituímos o valor padrão de `None` para `Query(None)`, o primeiro parâmetro de `Query` serve para o mesmo propósito: definir o valor padrão do parâmetro. +Note que substituímos o valor padrão de `None` para `Query(default=None)`, o primeiro parâmetro de `Query` serve para o mesmo propósito: definir o valor padrão do parâmetro. Então: ```Python -q: Optional[str] = Query(None) +q: Union[str, None] = Query(default=None) ``` ...Torna o parâmetro opcional, da mesma maneira que: ```Python -q: Optional[str] = None +q: Union[str, None] = None ``` Mas o declara explicitamente como um parâmetro de consulta. @@ -61,17 +61,17 @@ Mas o declara explicitamente como um parâmetro de consulta. Ou com: ```Python - = Query(None) + = Query(default=None) ``` E irá utilizar o `None` para detectar que o parâmetro de consulta não é obrigatório. - O `Optional` é apenas para permitir que seu editor de texto lhe dê um melhor suporte. + O `Union` é apenas para permitir que seu editor de texto lhe dê um melhor suporte. Então, podemos passar mais parâmetros para `Query`. Neste caso, o parâmetro `max_length` que se aplica a textos: ```Python -q: str = Query(None, max_length=50) +q: str = Query(default=None, max_length=50) ``` Isso irá validar os dados, mostrar um erro claro quando os dados forem inválidos, e documentar o parâmetro na *operação de rota* do esquema OpenAPI.. @@ -80,7 +80,7 @@ Isso irá validar os dados, mostrar um erro claro quando os dados forem inválid Você também pode incluir um parâmetro `min_length`: -```Python hl_lines="9" +```Python hl_lines="10" {!../../../docs_src/query_params_str_validations/tutorial003.py!} ``` @@ -88,7 +88,7 @@ Você também pode incluir um parâmetro `min_length`: Você pode definir uma expressão regular que combine com um padrão esperado pelo parâmetro: -```Python hl_lines="10" +```Python hl_lines="11" {!../../../docs_src/query_params_str_validations/tutorial004.py!} ``` @@ -126,13 +126,13 @@ q: str em vez desta: ```Python -q: Optional[str] = None +q: Union[str, None] = None ``` Mas agora nós o estamos declarando como `Query`, conforme abaixo: ```Python -q: Optional[str] = Query(None, min_length=3) +q: Union[str, None] = Query(default=None, min_length=3) ``` Então, quando você precisa declarar um parâmetro obrigatório utilizando o `Query`, você pode utilizar `...` como o primeiro argumento: diff --git a/docs/pt/docs/tutorial/query-params.md b/docs/pt/docs/tutorial/query-params.md new file mode 100644 index 000000000..189724396 --- /dev/null +++ b/docs/pt/docs/tutorial/query-params.md @@ -0,0 +1,224 @@ +# Parâmetros de Consulta + +Quando você declara outros parâmetros na função que não fazem parte dos parâmetros da rota, esses parâmetros são automaticamente interpretados como parâmetros de "consulta". + +```Python hl_lines="9" +{!../../../docs_src/query_params/tutorial001.py!} +``` + +A consulta é o conjunto de pares chave-valor que vai depois de `?` na URL, separado pelo caractere `&`. + +Por exemplo, na URL: + +``` +http://127.0.0.1:8000/items/?skip=0&limit=10 +``` + +...os parâmetros da consulta são: + +* `skip`: com o valor `0` +* `limit`: com o valor `10` + +Como eles são parte da URL, eles são "naturalmente" strings. + +Mas quando você declara eles com os tipos do Python (no exemplo acima, como `int`), eles são convertidos para aquele tipo e validados em relação a ele. + +Todo o processo que era aplicado para parâmetros de rota também é aplicado para parâmetros de consulta: + +* Suporte do editor (obviamente) +* "Parsing" de dados +* Validação de dados +* Documentação automática + +## Valores padrão + +Como os parâmetros de consulta não são uma parte fixa da rota, eles podem ser opcionais e podem ter valores padrão. + +No exemplo acima eles tem valores padrão de `skip=0` e `limit=10`. + +Então, se você for até a URL: + +``` +http://127.0.0.1:8000/items/ +``` + +Seria o mesmo que ir para: + +``` +http://127.0.0.1:8000/items/?skip=0&limit=10 +``` + +Mas, se por exemplo você for para: + +``` +http://127.0.0.1:8000/items/?skip=20 +``` + +Os valores dos parâmetros na sua função serão: + +* `skip=20`: Por que você definiu isso na URL +* `limit=10`: Por que esse era o valor padrão + +## Parâmetros opcionais + +Da mesma forma, você pode declarar parâmetros de consulta opcionais, definindo o valor padrão para `None`: + +=== "Python 3.6 and above" + + ```Python hl_lines="9" + {!> ../../../docs_src/query_params/tutorial002.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="7" + {!> ../../../docs_src/query_params/tutorial002_py310.py!} + ``` + +Nesse caso, o parâmetro da função `q` será opcional, e `None` será o padrão. + +!!! check "Verificar" + Você também pode notar que o **FastAPI** é esperto o suficiente para perceber que o parâmetro da rota `item_id` é um parâmetro da rota, e `q` não é, portanto, `q` é o parâmetro de consulta. + + +## Conversão dos tipos de parâmetros de consulta + +Você também pode declarar tipos `bool`, e eles serão convertidos: + +=== "Python 3.6 and above" + + ```Python hl_lines="9" + {!> ../../../docs_src/query_params/tutorial003.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="7" + {!> ../../../docs_src/query_params/tutorial003_py310.py!} + ``` + +Nesse caso, se você for para: + +``` +http://127.0.0.1:8000/items/foo?short=1 +``` + +ou + +``` +http://127.0.0.1:8000/items/foo?short=True +``` + +ou + +``` +http://127.0.0.1:8000/items/foo?short=true +``` + +ou + +``` +http://127.0.0.1:8000/items/foo?short=on +``` + +ou + +``` +http://127.0.0.1:8000/items/foo?short=yes +``` + +ou qualquer outra variação (tudo em maiúscula, primeira letra em maiúscula, etc), a sua função vai ver o parâmetro `short` com um valor `bool` de `True`. Caso contrário `False`. + +## Múltiplos parâmetros de rota e consulta + +Você pode declarar múltiplos parâmetros de rota e parâmetros de consulta ao mesmo tempo, o **FastAPI** vai saber o quê é o quê. + +E você não precisa declarar eles em nenhuma ordem específica. + +Eles serão detectados pelo nome: + +=== "Python 3.6 and above" + + ```Python hl_lines="8 10" + {!> ../../../docs_src/query_params/tutorial004.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="6 8" + {!> ../../../docs_src/query_params/tutorial004_py310.py!} + ``` + +## Parâmetros de consulta obrigatórios + +Quando você declara um valor padrão para parâmetros que não são de rota (até agora, nós vimos apenas parâmetros de consulta), então eles não são obrigatórios. + +Caso você não queira adicionar um valor específico mas queira apenas torná-lo opcional, defina o valor padrão como `None`. + +Porém, quando você quiser fazer com que o parâmetro de consulta seja obrigatório, você pode simplesmente não declarar nenhum valor como padrão. + +```Python hl_lines="6-7" +{!../../../docs_src/query_params/tutorial005.py!} +``` + +Aqui o parâmetro de consulta `needy` é um valor obrigatório, do tipo `str`. + +Se você abrir no seu navegador a URL: + +``` +http://127.0.0.1:8000/items/foo-item +``` + +... sem adicionar o parâmetro obrigatório `needy`, você verá um erro como: + +```JSON +{ + "detail": [ + { + "loc": [ + "query", + "needy" + ], + "msg": "field required", + "type": "value_error.missing" + } + ] +} +``` + +Como `needy` é um parâmetro obrigatório, você precisaria defini-lo na URL: + +``` +http://127.0.0.1:8000/items/foo-item?needy=sooooneedy +``` + +...isso deve funcionar: + +```JSON +{ + "item_id": "foo-item", + "needy": "sooooneedy" +} +``` + +E claro, você pode definir alguns parâmetros como obrigatórios, alguns possuindo um valor padrão, e outros sendo totalmente opcionais: + +=== "Python 3.6 and above" + + ```Python hl_lines="10" + {!> ../../../docs_src/query_params/tutorial006.py!} + ``` + +=== "Python 3.10 and above" + + ```Python hl_lines="8" + {!> ../../../docs_src/query_params/tutorial006_py310.py!} + ``` +Nesse caso, existem 3 parâmetros de consulta: + +* `needy`, um `str` obrigatório. +* `skip`, um `int` com o valor padrão `0`. +* `limit`, um `int` opcional. + +!!! tip "Dica" + Você também poderia usar `Enum` da mesma forma que com [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}. diff --git a/docs/pt/docs/tutorial/security/first-steps.md b/docs/pt/docs/tutorial/security/first-steps.md new file mode 100644 index 000000000..ed07d1c96 --- /dev/null +++ b/docs/pt/docs/tutorial/security/first-steps.md @@ -0,0 +1,181 @@ +# Segurança - Primeiros Passos + +Vamos imaginar que você tem a sua API **backend** em algum domínio. + +E você tem um **frontend** em outro domínio ou em um path diferente no mesmo domínio (ou em uma aplicação mobile). + +E você quer uma maneira de o frontend autenticar o backend, usando um **username** e **senha**. + +Nós podemos usar o **OAuth2** junto com o **FastAPI**. + +Mas, vamos poupar-lhe o tempo de ler toda a especificação apenas para achar as pequenas informações que você precisa. + +Vamos usar as ferramentas fornecidas pela **FastAPI** para lidar com segurança. + +## Como Parece + +Vamos primeiro usar o código e ver como funciona, e depois voltaremos para entender o que está acontecendo. + +## Crie um `main.py` +Copie o exemplo em um arquivo `main.py`: + +```Python +{!../../../docs_src/security/tutorial001.py!} +``` + +## Execute-o + +!!! informação + Primeiro, instale `python-multipart`. + + Ex: `pip install python-multipart`. + + Isso ocorre porque o **OAuth2** usa "dados de um formulário" para mandar o **username** e **senha**. + +Execute esse exemplo com: + +
+ +```console +$ uvicorn main:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +## Verifique-o + +Vá até a documentação interativa em: http://127.0.0.1:8000/docs. + +Você verá algo deste tipo: + + + +!!! marque o "botão de Autorizar!" + Você já tem um novo "botão de autorizar!". + + E seu *path operation* tem um pequeno cadeado no canto superior direito que você pode clicar. + +E se você clicar, você terá um pequeno formulário de autorização para digitar o `username` e `senha` (e outros campos opcionais): + + + +!!! nota + Não importa o que você digita no formulário, não vai funcionar ainda. Mas nós vamos chegar lá. + +Claro que este não é o frontend para os usuários finais, mas é uma ótima ferramenta automática para documentar interativamente toda sua API. + +Pode ser usado pelo time de frontend (que pode ser você no caso). + +Pode ser usado por aplicações e sistemas third party (de terceiros). + +E também pode ser usada por você mesmo, para debugar, checar e testar a mesma aplicação. + +## O Fluxo da `senha` + +Agora vamos voltar um pouco e entender o que é isso tudo. + +O "fluxo" da `senha` é um dos caminhos ("fluxos") definidos no OAuth2, para lidar com a segurança e autenticação. + +OAuth2 foi projetado para que o backend ou a API pudesse ser independente do servidor que autentica o usuário. + +Mas nesse caso, a mesma aplicação **FastAPI** irá lidar com a API e a autenticação. + +Então, vamos rever de um ponto de vista simplificado: + +* O usuário digita o `username` e a `senha` no frontend e aperta `Enter`. +* O frontend (rodando no browser do usuário) manda o `username` e a `senha` para uma URL específica na sua API (declarada com `tokenUrl="token"`). +* A API checa aquele `username` e `senha`, e responde com um "token" (nós não implementamos nada disso ainda). + * Um "token" é apenas uma string com algum conteúdo que nós podemos utilizar mais tarde para verificar o usuário. + * Normalmente, um token é definido para expirar depois de um tempo. + * Então, o usuário terá que se logar de novo depois de um tempo. + * E se o token for roubado, o risco é menor. Não é como se fosse uma chave permanente que vai funcionar para sempre (na maioria dos casos). + * O frontend armazena aquele token temporariamente em algum lugar. + * O usuário clica no frontend para ir à outra seção daquele frontend do aplicativo web. + * O frontend precisa buscar mais dados daquela API. + * Mas precisa de autenticação para aquele endpoint em específico. + * Então, para autenticar com nossa API, ele manda um header de `Autorização` com o valor `Bearer` mais o token. + * Se o token contém `foobar`, o conteúdo do header de `Autorização` será: `Bearer foobar`. + +## **FastAPI**'s `OAuth2PasswordBearer` + +**FastAPI** fornece várias ferramentas, em diferentes níveis de abstração, para implementar esses recursos de segurança. + +Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`. + +!!! informação + Um token "bearer" não é a única opção. + + Mas é a melhor no nosso caso. + + E talvez seja a melhor para a maioria dos casos, a não ser que você seja um especialista em OAuth2 e saiba exatamente o porquê de existir outras opções que se adequam melhor às suas necessidades. + + Nesse caso, **FastAPI** também fornece as ferramentas para construir. + +Quando nós criamos uma instância da classe `OAuth2PasswordBearer`, nós passamos pelo parâmetro `tokenUrl` Esse parâmetro contém a URL que o client (o frontend rodando no browser do usuário) vai usar para mandar o `username` e `senha` para obter um token. + +```Python hl_lines="6" +{!../../../docs_src/security/tutorial001.py!} +``` + +!!! dica + Esse `tokenUrl="token"` se refere a uma URL relativa que nós não criamos ainda. Como é uma URL relativa, é equivalente a `./token`. + + Porque estamos usando uma URL relativa, se sua API estava localizada em `https://example.com/`, então irá referir-se à `https://example.com/token`. Mas se sua API estava localizada em `https://example.com/api/v1/`, então irá referir-se à `https://example.com/api/v1/token`. + + Usar uma URL relativa é importante para garantir que sua aplicação continue funcionando, mesmo em um uso avançado tipo [Atrás de um Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}. + +Esse parâmetro não cria um endpoint / *path operation*, mas declara que a URL `/token` vai ser aquela que o client deve usar para obter o token. Essa informação é usada no OpenAPI, e depois na API Interativa de documentação de sistemas. + +Em breve também criaremos o atual path operation. + +!!! informação + Se você é um "Pythonista" muito rigoroso, você pode não gostar do estilo do nome do parâmetro `tokenUrl` em vez de `token_url`. + + Isso ocorre porque está utilizando o mesmo nome que está nas especificações do OpenAPI. Então, se você precisa investigar mais sobre qualquer um desses esquemas de segurança, você pode simplesmente copiar e colar para encontrar mais informações sobre isso. + +A variável `oauth2_scheme` é um instância de `OAuth2PasswordBearer`, mas também é um "callable". + +Pode ser chamada de: + +```Python +oauth2_scheme(some, parameters) +``` + +Então, pode ser usado com `Depends`. + +## Use-o + +Agora você pode passar aquele `oauth2_scheme` em uma dependência com `Depends`. + +```Python hl_lines="10" +{!../../../docs_src/security/tutorial001.py!} +``` + +Esse dependência vai fornecer uma `str` que é atribuído ao parâmetro `token da *função do path operation* + +A **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema da OpenAPI (e na documentação da API automática). + +!!! informação "Detalhes técnicos" + **FastAPI** saberá que pode usar a classe `OAuth2PasswordBearer` (declarada na dependência) para definir o esquema de segurança na OpenAPI porque herda de `fastapi.security.oauth2.OAuth2`, que por sua vez herda de `fastapi.security.base.Securitybase`. + + Todos os utilitários de segurança que se integram com OpenAPI (e na documentação da API automática) herdam de `SecurityBase`, é assim que **FastAPI** pode saber como integrá-los no OpenAPI. + +## O que ele faz + +Ele irá e olhará na requisição para aquele header de `Autorização`, verificará se o valor é `Bearer` mais algum token, e vai retornar o token como uma `str` + +Se ele não ver o header de `Autorização` ou o valor não tem um token `Bearer`, vai responder com um código de erro 401 (`UNAUTHORIZED`) diretamente. + +Você nem precisa verificar se o token existe para retornar um erro. Você pode ter certeza de que se a sua função for executada, ela terá um `str` nesse token. + +Você já pode experimentar na documentação interativa: + + + +Não estamos verificando a validade do token ainda, mas isso já é um começo + +## Recapitulando + +Então, em apenas 3 ou 4 linhas extras, você já tem alguma forma primitiva de segurança. diff --git a/docs/pt/mkdocs.yml b/docs/pt/mkdocs.yml index f202f306d..59ee3cc88 100644 --- a/docs/pt/mkdocs.yml +++ b/docs/pt/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -58,20 +64,29 @@ nav: - tutorial/index.md - tutorial/first-steps.md - tutorial/path-params.md + - tutorial/query-params.md + - tutorial/body.md - tutorial/body-fields.md + - tutorial/extra-data-types.md - tutorial/query-params-str-validations.md + - tutorial/cookie-params.md + - tutorial/header-params.md + - tutorial/handling-errors.md - Segurança: - tutorial/security/index.md + - tutorial/background-tasks.md - Guia de Usuário Avançado: - advanced/index.md - Implantação: - deployment/index.md - deployment/versions.md - deployment/https.md + - deployment/deta.md - alternatives.md - history-design-future.md - external-links.md - benchmarks.md +- help-fastapi.md markdown_extensions: - toc: permalink: true @@ -89,6 +104,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -117,8 +134,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -127,6 +148,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -135,6 +158,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md new file mode 100644 index 000000000..4c44fc22d --- /dev/null +++ b/docs/ru/docs/async.md @@ -0,0 +1,505 @@ +# Конкурентность и async / await + +Здесь приведена подробная информация об использовании синтаксиса `async def` при написании *функций обработки пути*, а также рассмотрены основы асинхронного программирования, конкурентности и параллелизма. + +## Нет времени? + +TL;DR: + +Допустим, вы используете сторонюю библиотеку, которая требует вызова с ключевым словом `await`: + +```Python +results = await some_library() +``` + +В этом случае *функции обработки пути* необходимо объявлять с использованием синтаксиса `async def`: + +```Python hl_lines="2" +@app.get('/') +async def read_results(): + results = await some_library() + return results +``` + +!!! note + `await` можно использовать только внутри функций, объявленных с использованием `async def`. + +--- + +Если вы обращаетесь к сторонней библиотеке, которая с чем-то взаимодействует +(с базой данных, API, файловой системой и т. д.), и не имеет поддержки синтаксиса `await` +(что относится сейчас к большинству библиотек для работы с базами данных), то +объявляйте *функции обработки пути* обычным образом с помощью `def`, например: + +```Python hl_lines="2" +@app.get('/') +def results(): + results = some_library() + return results +``` + +--- + +Если вашему приложению (странным образом) не нужно ни с чем взаимодействовать и, соответственно, +ожидать ответа, используйте `async def`. + +--- + +Если вы не уверены, используйте обычный синтаксис `def`. + +--- + +**Примечание**: при необходимости можно смешивать `def` и `async def` в *функциях обработки пути* +и использовать в каждом случае наиболее подходящий синтаксис. А FastAPI сделает с этим всё, что нужно. + +В любом из описанных случаев FastAPI работает асинхронно и очень быстро. + +Однако придерживаясь указанных советов, можно получить дополнительную оптимизацию производительности. + +## Технические подробности + +Современные версии Python поддерживают разработку так называемого **"асинхронного кода"** посредством написания **"сопрограмм"** с использованием синтаксиса **`async` и `await`**. + +Ниже разберём эту фразу по частям: + +* **Асинхронный код** +* **`async` и `await`** +* **Сопрограммы** + +## Асинхронный код + +Асинхронный код означает, что в языке 💬 есть возможность сообщить машине / программе 🤖, +что в определённой точке кода ей 🤖 нужно будет ожидать завершения выполнения *чего-то ещё* в другом месте. Допустим это *что-то ещё* называется "медленный файл" 📝. + +И пока мы ждём завершения работы с "медленным файлом" 📝, компьютер может переключиться для выполнения других задач. + +Но при каждой возможности компьютер / программа 🤖 будет возвращаться обратно. Например, если он 🤖 опять окажется в режиме ожидания, или когда закончит всю работу. В этом случае компьютер 🤖 проверяет, не завершена ли какая-нибудь из текущих задач. + +Потом он 🤖 берёт первую выполненную задачу (допустим, наш "медленный файл" 📝) и продолжает работу, производя с ней необходимые действия. + +Вышеупомянутое "что-то ещё", завершения которого приходится ожидать, обычно относится к достаточно "медленным" операциям I/O (по сравнению со скоростью работы процессора и оперативной памяти), например: + +* отправка данных от клиента по сети +* получение клиентом данных, отправленных вашей программой по сети +* чтение системой содержимого файла с диска и передача этих данных программе +* запись на диск данных, которые программа передала системе +* обращение к удалённому API +* ожидание завершения операции с базой данных +* получение результатов запроса к базе данных +* и т. д. + +Поскольку в основном время тратится на ожидание выполнения операций I/O, +их обычно называют операциями, ограниченными скоростью ввода-вывода. + +Код называют "асинхронным", потому что компьютеру / программе не требуется "синхронизироваться" с медленной задачей и, +будучи в простое, ожидать момента её завершения, с тем чтобы забрать результат и продолжить работу. + +Вместо этого в "асинхронной" системе завершённая задача может немного подождать (буквально несколько микросекунд), +пока компьютер / программа занимается другими важными вещами, с тем чтобы потом вернуться, +забрать результаты выполнения и начать их обрабатывать. + +"Синхронное" исполнение (в противовес "асинхронному") также называют "последовательным", +потому что компьютер / программа последовательно выполняет все требуемые шаги перед тем, как перейти к следующей задаче, +даже если в процессе приходится ждать. + +### Конкурентность и бургеры + +Тот **асинхронный** код, о котором идёт речь выше, иногда называют **"конкурентностью"**. Она отличается от **"параллелизма"**. + +Да, **конкурентность** и **параллелизм** подразумевают, что разные вещи происходят примерно в одно время. + +Но внутреннее устройство **конкурентности** и **параллелизма** довольно разное. + +Чтобы это понять, представьте такую картину: + +### Конкурентные бургеры + + + +Вы идёте со своей возлюбленной 😍 в фастфуд 🍔 и становитесь в очередь, в это время кассир 💁 принимает заказы у посетителей перед вами. + +Когда наконец подходит очередь, вы заказываете парочку самых вкусных и навороченных бургеров 🍔, один для своей возлюбленной 😍, а другой себе. + +Отдаёте деньги 💸. + +Кассир 💁 что-то говорит поварам на кухне 👨‍🍳, теперь они знают, какие бургеры нужно будет приготовить 🍔 +(но пока они заняты бургерами предыдущих клиентов). + +Кассир 💁 отдаёт вам чек с номером заказа. + +В ожидании еды вы идёте со своей возлюбленной 😍 выбрать столик, садитесь и довольно продолжительное время общаетесь 😍 +(поскольку ваши бургеры самые навороченные, готовятся они не так быстро ✨🍔✨). + +Сидя за столиком с возлюбленной 😍 в ожидании бургеров 🍔, вы отлично проводите время, +восхищаясь её великолепием, красотой и умом ✨😍✨. + +Всё ещё ожидая заказ и болтая со своей возлюбленной 😍, время от времени вы проверяете, +какой номер горит над прилавком, и не подошла ли уже ваша очередь. + +И вот наконец настаёт этот момент, и вы идёте к стойке, чтобы забрать бургеры 🍔 и вернуться за столик. + +Вы со своей возлюбленной 😍 едите бургеры 🍔 и отлично проводите время ✨. + +--- + +А теперь представьте, что в этой небольшой истории вы компьютер / программа 🤖. + +В очереди вы просто глазеете по сторонам 😴, ждёте и ничего особо "продуктивного" не делаете. +Но очередь движется довольно быстро, поскольку кассир 💁 только принимает заказы (а не занимается приготовлением еды), так что ничего страшного. + +Когда подходит очередь вы наконец предпринимаете "продуктивные" действия 🤓: просматриваете меню, выбираете в нём что-то, узнаёте, что хочет ваша возлюбленная 😍, собираетесь оплатить 💸, смотрите, какую достали карту, проверяете, чтобы с вас списали верную сумму, и что в заказе всё верно и т. д. + +И хотя вы всё ещё не получили бургеры 🍔, ваша работа с кассиром 💁 ставится "на паузу" ⏸, +поскольку теперь нужно ждать 🕙, когда заказ приготовят. + +Но отойдя с номерком от прилавка, вы садитесь за столик и можете переключить 🔀 внимание +на свою возлюбленную 😍 и "работать" ⏯ 🤓 уже над этим. И вот вы снова очень +"продуктивны" 🤓, мило болтаете вдвоём и всё такое 😍. + +В какой-то момент кассир 💁 поместит на табло ваш номер, подразумевая, что бургеры готовы 🍔, но вы не станете подскакивать как умалишённый, лишь только увидев на экране свою очередь. Вы уверены, что ваши бургеры 🍔 никто не утащит, ведь у вас свой номерок, а у других свой. + +Поэтому вы подождёте, пока возлюбленная 😍 закончит рассказывать историю (закончите текущую работу ⏯ / задачу в обработке 🤓), +и мило улыбнувшись, скажете, что идёте забирать заказ ⏸. + +И вот вы подходите к стойке 🔀, к первоначальной задаче, которая уже завершена ⏯, берёте бургеры 🍔, говорите спасибо и относите заказ за столик. На этом заканчивается этап / задача взаимодействия с кассой ⏹. +В свою очередь порождается задача "поедание бургеров" 🔀 ⏯, но предыдущая ("получение бургеров") завершена ⏹. + +### Параллельные бургеры + +Теперь представим, что вместо бургерной "Конкурентные бургеры" вы решили сходить в "Параллельные бургеры". + +И вот вы идёте со своей возлюбленной 😍 отведать параллельного фастфуда 🍔. + +Вы становитесь в очередь пока несколько (пусть будет 8) кассиров, которые по совместительству ещё и повары 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, принимают заказы у посетителей перед вами. + +При этом клиенты не отходят от стойки и ждут 🕙 получения еды, поскольку каждый +из 8 кассиров идёт на кухню готовить бургеры 🍔, а только потом принимает следующий заказ. + +Наконец настаёт ваша очередь, и вы просите два самых навороченных бургера 🍔, один для дамы сердца 😍, а другой себе. + +Ни о чём не жалея, расплачиваетесь 💸. + +И кассир уходит на кухню 👨‍🍳. + +Вам приходится ждать перед стойкой 🕙, чтобы никто по случайности не забрал ваши бургеры 🍔, ведь никаких номерков у вас нет. + +Поскольку вы с возлюбленной 😍 хотите получить заказ вовремя 🕙, и следите за тем, чтобы никто не вклинился в очередь, +у вас не получается уделять должного внимание своей даме сердца 😞. + +Это "синхронная" работа, вы "синхронизированы" с кассиром/поваром 👨‍🍳. Приходится ждать 🕙 у стойки, +когда кассир/повар 👨‍🍳 закончит делать бургеры 🍔 и вручит вам заказ, иначе его случайно может забрать кто-то другой. + +Наконец кассир/повар 👨‍🍳 возвращается с бургерами 🍔 после невыносимо долгого ожидания 🕙 за стойкой. + +Вы скорее забираете заказ 🍔 и идёте с возлюбленной 😍 за столик. + +Там вы просто едите эти бургеры, и на этом всё 🍔 ⏹. + +Вам не особо удалось пообщаться, потому что большую часть времени 🕙 пришлось провести у кассы 😞. + +--- + +В описанном сценарии вы компьютер / программа 🤖 с двумя исполнителями (вы и ваша возлюбленная 😍), +на протяжении долгого времени 🕙 вы оба уделяете всё внимание ⏯ задаче "ждать на кассе". + +В этом ресторане быстрого питания 8 исполнителей (кассиров/поваров) 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳. +Хотя в бургерной конкурентного типа было всего два (один кассир и один повар) 💁 👨‍🍳. + +Несмотря на обилие работников, опыт в итоге получился не из лучших 😞. + +--- + +Так бы выглядел аналог истории про бургерную 🍔 в "параллельном" мире. + +Вот более реалистичный пример. Представьте себе банк. + +До недавних пор в большинстве банков было несколько кассиров 👨‍💼👨‍💼👨‍💼👨‍💼 и длинные очереди 🕙🕙🕙🕙🕙🕙🕙🕙. + +Каждый кассир обслуживал одного клиента, потом следующего 👨‍💼⏯. + +Нужно было долгое время 🕙 стоять перед окошком вместе со всеми, иначе пропустишь свою очередь. + +Сомневаюсь, что у вас бы возникло желание прийти с возлюбленной 😍 в банк 🏦 оплачивать налоги. + +### Выводы о бургерах + +В нашей истории про поход в фастфуд за бургерами приходится много ждать 🕙, +поэтому имеет смысл организовать конкурентную систему ⏸🔀⏯. + +И то же самое с большинством веб-приложений. + +Пользователей очень много, но ваш сервер всё равно вынужден ждать 🕙 запросы по их слабому интернет-соединению. + +Потом снова ждать 🕙, пока вернётся ответ. + + +Это ожидание 🕙 измеряется микросекундами, но если всё сложить, то набегает довольно много времени. + +Вот почему есть смысл использовать асинхронное ⏸🔀⏯ программирование при построении веб-API. + +Большинство популярных фреймворков (включая Flask и Django) создавались +до появления в Python новых возможностей асинхронного программирования. Поэтому +их можно разворачивать с поддержкой параллельного исполнения или асинхронного +программирования старого типа, которое не настолько эффективно. + +При том, что основная спецификация асинхронного взаимодействия Python с веб-сервером +(ASGI) +была разработана командой Django для внедрения поддержки веб-сокетов. + +Именно асинхронность сделала NodeJS таким популярным (несмотря на то, что он не параллельный), +и в этом преимущество Go как языка программирования. + +И тот же уровень производительности даёт **FastAPI**. + +Поскольку можно использовать преимущества параллелизма и асинхронности вместе, +вы получаете производительность лучше, чем у большинства протестированных NodeJS фреймворков +и на уровне с Go, который является компилируемым языком близким к C (всё благодаря Starlette). + +### Получается, конкурентность лучше параллелизма? + +Нет! Мораль истории совсем не в этом. + +Конкурентность отличается от параллелизма. Она лучше в **конкретных** случаях, где много времени приходится на ожидание. +Вот почему она зачастую лучше параллелизма при разработке веб-приложений. Но это не значит, что конкурентность лучше в любых сценариях. + +Давайте посмотрим с другой стороны, представьте такую картину: + +> Вам нужно убраться в большом грязном доме. + +*Да, это вся история*. + +--- + +Тут не нужно нигде ждать 🕙, просто есть куча работы в разных частях дома. + +Можно организовать очередь как в примере с бургерами, сначала гостиная, потом кухня, +но это ни на что не повлияет, поскольку вы нигде не ждёте 🕙, а просто трёте да моете. + +И понадобится одинаковое количество времени с очередью (конкурентностью) и без неё, +и работы будет сделано тоже одинаковое количество. + +Однако в случае, если бы вы могли привести 8 бывших кассиров/поваров, а ныне уборщиков 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, +и каждый из них (вместе с вами) взялся бы за свой участок дома, +с такой помощью вы бы закончили намного быстрее, делая всю работу **параллельно**. + +В описанном сценарии каждый уборщик (включая вас) был бы исполнителем, занятым на своём участке работы. + +И поскольку большую часть времени выполнения занимает реальная работа (а не ожидание), +а работу в компьютере делает ЦП, +такие задачи называют ограниченными производительностью процессора. + +--- + +Ограничение по процессору проявляется в операциях, где требуется выполнять сложные математические вычисления. + +Например: + +* Обработка **звука** или **изображений**. +* **Компьютерное зрение**: изображение состоит из миллионов пикселей, в каждом пикселе 3 составляющих цвета, +обработка обычно требует проведения расчётов по всем пикселям сразу. +* **Машинное обучение**: здесь обычно требуется умножение "матриц" и "векторов". +Представьте гигантскую таблицу с числами в Экселе, и все их надо одновременно перемножить. +* **Глубокое обучение**: это область *машинного обучения*, поэтому сюда подходит то же описание. +Просто у вас будет не одна таблица в Экселе, а множество. В ряде случаев используется +специальный процессор для создания и / или использования построенных таким образом моделей. + +### Конкурентность + параллелизм: Веб + машинное обучение + +**FastAPI** предоставляет возможности конкуретного программирования, +которое очень распространено в веб-разработке (именно этим славится NodeJS). + +Кроме того вы сможете использовать все преимущества параллелизма и +многопроцессорности (когда несколько процессов работают параллельно), +если рабочая нагрузка предполагает **ограничение по процессору**, +как, например, в системах машинного обучения. + +Необходимо также отметить, что Python является главным языком в области +**дата-сайенс**, +машинного обучения и, особенно, глубокого обучения. Всё это делает FastAPI +отличным вариантом (среди многих других) для разработки веб-API и приложений +в области дата-сайенс / машинного обучения. + +Как добиться такого параллелизма в эксплуатации описано в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}. + +## `async` и `await` + +В современных версиях Python разработка асинхронного кода реализована очень интуитивно. +Он выглядит как обычный "последовательный" код и самостоятельно выполняет "ожидание", когда это необходимо. + +Если некая операция требует ожидания перед тем, как вернуть результат, и +поддерживает современные возможности Python, код можно написать следующим образом: + +```Python +burgers = await get_burgers(2) +``` + +Главное здесь слово `await`. Оно сообщает интерпретатору, что необходимо дождаться ⏸ +пока `get_burgers(2)` закончит свои дела 🕙, и только после этого сохранить результат в `burgers`. +Зная это, Python может пока переключиться на выполнение других задач 🔀 ⏯ +(например получение следующего запроса). + +Чтобы ключевое слово `await` сработало, оно должно находиться внутри функции, +которая поддерживает асинхронность. Для этого вам просто нужно объявить её как `async def`: + +```Python hl_lines="1" +async def get_burgers(number: int): + # Готовим бургеры по специальному асинхронному рецепту + return burgers +``` + +...вместо `def`: + +```Python hl_lines="2" +# Это не асинхронный код +def get_sequential_burgers(number: int): + # Готовим бургеры последовательно по шагам + return burgers +``` + +Объявление `async def` указывает интерпретатору, что внутри этой функции +следует ожидать выражений `await`, и что можно поставить выполнение такой функции на "паузу" ⏸ и +переключиться на другие задачи 🔀, с тем чтобы вернуться сюда позже. + +Если вы хотите вызвать функцию с `async def`, вам нужно "ожидать" её. +Поэтому такое не сработает: + +```Python +# Это не заработает, поскольку get_burgers объявлена с использованием async def +burgers = get_burgers(2) +``` + +--- + +Если сторонняя библиотека требует вызывать её с ключевым словом `await`, +необходимо писать *функции обработки пути* с использованием `async def`, например: + +```Python hl_lines="2-3" +@app.get('/burgers') +async def read_burgers(): + burgers = await get_burgers(2) + return burgers +``` + +### Технические подробности + +Как вы могли заметить, `await` может применяться только в функциях, объявленных с использованием `async def`. + + +Но выполнение такой функции необходимо "ожидать" с помощью `await`. +Это означает, что её можно вызвать только из другой функции, которая тоже объявлена с `async def`. + +Но как же тогда появилась первая курица? В смысле... как нам вызвать первую асинхронную функцию? + +При работе с **FastAPI** просто не думайте об этом, потому что "первой" функцией является ваша *функция обработки пути*, +и дальше с этим разберётся FastAPI. + +Кроме того, если хотите, вы можете использовать синтаксис `async` / `await` и без FastAPI. + +### Пишите свой асинхронный код + +Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми как со стандартной библиотекой asyncio в Python, так и с Trio. + +В частности, вы можете напрямую использовать AnyIO в тех проектах, где требуется более сложная логика работы с конкурентностью. + +Даже если вы не используете FastAPI, вы можете писать асинхронные приложения с помощью AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например *структурную конкурентность*). + +### Другие виды асинхронного программирования + +Стиль написания кода с `async` и `await` появился в языке Python относительно недавно. + +Но он сильно облегчает работу с асинхронным кодом. + +Ровно такой же синтаксис (ну или почти такой же) недавно был включён в современные версии JavaScript (в браузере и NodeJS). + +До этого поддержка асинхронного кода была реализована намного сложнее, и его было труднее воспринимать. + +В предыдущих версиях Python для этого использовались потоки или Gevent. Но такой код намного сложнее понимать, отлаживать и мысленно представлять. + +Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели +"обратные вызовы". Что выливалось в +ад обратных вызовов. + +## Сопрограммы + +**Корути́на** (или же сопрограмма) — это крутое словечко для именования той сущности, +которую возвращает функция `async def`. Python знает, что её можно запустить, как и обычную функцию, +но кроме того сопрограмму можно поставить на паузу ⏸ в том месте, где встретится слово `await`. + +Всю функциональность асинхронного программирования с использованием `async` и `await` +часто обобщают словом "корутины". Они аналогичны "горутинам", ключевой особенности +языка Go. + +## Заключение + +В самом начале была такая фраза: + +> Современные версии Python поддерживают разработку так называемого +**"асинхронного кода"** посредством написания **"сопрограмм"** с использованием +синтаксиса **`async` и `await`**. + +Теперь всё должно звучать понятнее. ✨ + +На этом основана работа FastAPI (посредством Starlette), и именно это +обеспечивает его высокую производительность. + +## Очень технические подробности + +!!! warning + Этот раздел читать не обязательно. + + Здесь приводятся подробности внутреннего устройства **FastAPI**. + + Но если вы обладаете техническими знаниями (корутины, потоки, блокировка и т. д.) + и вам интересно, как FastAPI обрабатывает `async def` в отличие от обычных `def`, + читайте дальше. + +### Функции обработки пути + +Когда вы объявляете *функцию обработки пути* обычным образом с ключевым словом `def` +вместо `async def`, FastAPI ожидает её выполнения, запустив функцию во внешнем +пуле потоков, а не напрямую (это бы заблокировало сервер). + +Если ранее вы использовали другой асинхронный фреймворк, который работает иначе, +и привыкли объявлять простые вычислительные *функции* через `def` ради +незначительного прироста скорости (порядка 100 наносекунд), обратите внимание, +что с **FastAPI** вы получите противоположный эффект. В таком случае больше подходит +`async def`, если только *функция обработки пути* не использует код, приводящий +к блокировке I/O. + + + +Но в любом случае велика вероятность, что **FastAPI** [окажется быстрее](/#performance){.internal-link target=_blank} +другого фреймворка (или хотя бы на уровне с ним). + +### Зависимости + +То же относится к зависимостям. Если это обычная функция `def`, а не `async def`, +она запускается во внешнем пуле потоков. + +### Подзависимости + +Вы можете объявить множество ссылающихся друг на друга зависимостей и подзависимостей +(в виде параметров при определении функции). Какие-то будут созданы с помощью `async def`, +другие обычным образом через `def`, и такая схема вполне работоспособна. Функции, +объявленные с помощью `def` будут запускаться на внешнем потоке (из пула), +а не с помощью `await`. + +### Другие служебные функции + +Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять +с использованием `def` или `async def`. FastAPI не будет влиять на то, как вы +их запускаете. + +Этим они отличаются от функций, которые FastAPI вызывает самостоятельно: +*функции обработки пути* и зависимости. + +Если служебная функция объявлена с помощью `def`, она будет вызвана напрямую +(как вы и написали в коде), а не в отдельном потоке. Если же она объявлена с +помощью `async def`, её вызов должен осуществляться с ожиданием через `await`. + +--- + + +Ещё раз повторим, что все эти технические подробности полезны, только если вы специально их искали. + +В противном случае просто ознакомьтесь с основными принципами в разделе выше: Нет времени?. diff --git a/docs/ru/docs/deployment/versions.md b/docs/ru/docs/deployment/versions.md new file mode 100644 index 000000000..91b9038e9 --- /dev/null +++ b/docs/ru/docs/deployment/versions.md @@ -0,0 +1,87 @@ +# О версиях FastAPI + +**FastAPI** уже используется в продакшене во многих приложениях и системах. Покрытие тестами поддерживается на уровне 100%. Однако его разработка все еще продолжается. + +Часто добавляются новые функции, регулярно исправляются баги, код продолжает постоянно совершенствоваться. + +По указанным причинам текущие версии до сих пор `0.x.x`. Это говорит о том, что каждая версия может содержать обратно несовместимые изменения, следуя соглашению о Семантическом Версионировании. + +Уже сейчас вы можете создавать приложения в продакшене, используя **FastAPI** (и скорее всего так и делаете), главное убедиться в том, что вы используете версию, которая корректно работает с вашим кодом. + +## Закрепите вашу версию `fastapi` + +Первым делом вам следует "закрепить" конкретную последнюю используемую версию **FastAPI**, которая корректно работает с вашим приложением. + +Например, в своём приложении вы используете версию `0.45.0`. + +Если вы используете файл `requirements.txt`, вы можете указать версию следующим способом: + +```txt +fastapi==0.45.0 +``` + +это означает, что вы будете использовать именно версию `0.45.0`. + +Или вы можете закрепить версию следующим способом: + +```txt +fastapi>=0.45.0,<0.46.0 +``` + +это значит, что вы используете версии `0.45.0` или выше, но меньше чем `0.46.0`. Например, версия `0.45.2` все еще будет подходить. + +Если вы используете любой другой инструмент для управления зависимостями, например Poetry, Pipenv или др., у них у всех имеется способ определения специфической версии для ваших пакетов. + +## Доступные версии + +Вы можете посмотреть доступные версии (например, проверить последнюю на данный момент) в [примечаниях к выпуску](../release-notes.md){.internal-link target=_blank}. + +## О версиях + +Следуя соглашению о Семантическом Версионировании, любые версии ниже `1.0.0` потенциально могут добавить обратно несовместимые изменения. + +FastAPI следует соглашению в том, что любые изменения "ПАТЧ"-версии предназначены для исправления багов и внесения обратно совместимых изменений. + +!!! Подсказка + "ПАТЧ" - это последнее число. Например, в `0.2.3`, ПАТЧ-версия - это `3`. + +Итак, вы можете закрепить версию следующим образом: + +```txt +fastapi>=0.45.0,<0.46.0 +``` + +Обратно несовместимые изменения и новые функции добавляются в "МИНОРНЫЕ" версии. + +!!! Подсказка + "МИНОРНАЯ" версия - это число в середине. Например, в `0.2.3` МИНОРНАЯ версия - это `2`. + +## Обновление версий FastAPI + +Вам следует добавить тесты для вашего приложения. + +С помощью **FastAPI** это очень просто (благодаря Starlette), см. документацию: [Тестирование](../tutorial/testing.md){.internal-link target=_blank} + +После создания тестов вы можете обновить свою версию **FastAPI** до более новой. После этого следует убедиться, что ваш код работает корректно, запустив тесты. + +Если все работает корректно, или после внесения необходимых изменений все ваши тесты проходят, только тогда вы можете закрепить вашу новую версию `fastapi`. + +## О Starlette + +Не следует закреплять версию `starlette`. + +Разные версии **FastAPI** будут использовать более новые версии Starlette. + +Так что решение об используемой версии Starlette, вы можете оставить **FastAPI**. + +## О Pydantic + +Pydantic включает свои собственные тесты для **FastAPI**, так что новые версии Pydantic (выше `1.0.0`) всегда совместимы с FastAPI. + +Вы можете закрепить любую версию Pydantic, которая вам подходит, выше `1.0.0` и ниже `2.0.0`. + +Например: + +```txt +pydantic>=1.2.0,<2.0.0 +``` diff --git a/docs/ru/docs/features.md b/docs/ru/docs/features.md new file mode 100644 index 000000000..0cec4eee2 --- /dev/null +++ b/docs/ru/docs/features.md @@ -0,0 +1,203 @@ +# Основные свойства + +## Основные свойства FastAPI + +**FastAPI** предлагает вам следующее: + +### Использование открытых стандартов + +* OpenAPI для создания API, включая объявления операций пути, параметров, тела запроса, безопасности и т.д. + + +* Автоматическое документирование моделей данных в соответствии с JSON Schema (так как спецификация OpenAPI сама основана на JSON Schema). +* Разработан, придерживаясь этих стандартов, после тщательного их изучения. Эти стандарты изначально включены во фреймфорк, а не являются дополнительной надстройкой. +* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках. + +### Автоматически генерируемая документация + +Интерактивная документация для API и исследования пользовательских веб-интерфейсов. Поскольку этот фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из которых включены по умолчанию. + +* Swagger UI, с интерактивным взаимодействием, вызывает и тестирует ваш API прямо из браузера. + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* Альтернативная документация API в ReDoc. + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Только современный Python + +Все эти возможности основаны на стандартных **аннотациях типов Python 3.6** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только лишь стандартный современный Python. + +Если вам нужно освежить знания, как использовать аннотации типов в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Введение в аннотации типов Python¶ +](python-types.md){.internal-link target=_blank}. + +Вы пишете на стандартном Python с аннотациями типов: + +```Python +from datetime import date + +from pydantic import BaseModel + +# Объявляем параметр user_id с типом `str` +# и получаем поддержку редактора внутри функции +def main(user_id: str): + return user_id + + +# Модель Pydantic +class User(BaseModel): + id: int + name: str + joined: date +``` + +Это можно использовать так: + +```Python +my_user: User = User(id=3, name="John Doe", joined="2018-07-19") + +second_user_data = { + "id": 4, + "name": "Mary", + "joined": "2018-11-30", +} + +my_second_user: User = User(**second_user_data) +``` + +!!! Информация + `**second_user_data` означает: + + Передать ключи и значения словаря `second_user_data`, в качестве аргументов типа "ключ-значение", это эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")` . + +### Поддержка редакторов (IDE) + +Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода. + +В опросе Python-разработчиков было выяснено, что наиболее часто используемой функцией редакторов, является "автодополнение". + +Вся структура **FastAPI** основана на удовлетворении этой возможности. Автодополнение работает везде. + +Вам редко нужно будет возвращаться к документации. + +Вот как ваш редактор может вам помочь: + +* в Visual Studio Code: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +* в PyCharm: + +![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png) + +Вы будете получать автодополнение кода даже там, где вы считали это невозможным раньше. +Как пример, ключ `price` внутри тела JSON (который может быть вложенным), приходящего в запросе. + +Больше никаких неправильных имён ключей, метания по документации или прокручивания кода вверх и вниз, в попытках узнать - использовали вы ранее `username` или `user_name`. + +### Краткость +FastAPI имеет продуманные значения **по умолчанию** для всего, с произвольными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно и определять необходимый вам API. + +Но, по умолчанию, всё это **"и так работает"**. + +### Проверка значений + +* Проверка значений для большинства (или всех?) **типов данных** Python, включая: + * Объекты JSON (`dict`). + * Массивы JSON (`list`) с установленными типами элементов. + * Строковые (`str`) поля с ограничением минимальной и максимальной длины. + * Числа (`int`, `float`) с минимальными и максимальными значениями и т.п. + +* Проверка для более экзотических типов, таких как: + * URL. + * Email. + * UUID. + * ...и другие. + +Все проверки обрабатываются хорошо зарекомендовавшим себя и надежным **Pydantic**. + +### Безопасность и аутентификация + +Встроеные функции безопасности и аутентификации. Без каких-либо компромиссов с базами данных или моделями данных. + +Все схемы безопасности, определённые в OpenAPI, включая: + +* HTTP Basic. +* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. +* Ключи API в: + * Заголовках. + * Параметрах запросов. + * Cookies и т.п. + +Вдобавок все функции безопасности от Starlette (включая **сессионные cookies**). + +Все инструменты и компоненты спроектированы для многократного использования и легко интегрируются с вашими системами, хранилищами данных, реляционными и NoSQL базами данных и т. д. + +### Внедрение зависимостей + +FastAPI включает в себя чрезвычайно простую в использовании, но чрезвычайно мощную систему Внедрения зависимостей. + +* Даже зависимости могут иметь зависимости, создавая иерархию или **"графы" зависимостей**. +* Всё **автоматически обрабатывается** фреймворком. +* Все зависимости могут запрашивать данные из запросов и **дополнять операции пути** ограничениями и автоматической документацией. +* **Автоматическая проверка** даже для параметров *операций пути*, определенных в зависимостях. +* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т.д. +* **Никаких компромиссов** с базами данных, интерфейсами и т.д. Но легкая интеграция со всеми ними. + +### Нет ограничений на "Плагины" + +Или, другими словами, нет сложностей с ними, импортируйте и используйте нужный вам код. + +Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать "плагин" для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*. + +### Проверен + +* 100% покрытие тестами. +* 100% аннотирование типов в кодовой базе. +* Используется в реально работающих приложениях. + +## Основные свойства Starlette + +**FastAPI** основан на Starlette и полностью совместим с ним. Так что, любой дополнительный код Starlette, который у вас есть, будет также работать. + +На самом деле, `FastAPI` - это класс, унаследованный от `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же. + +С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI это всего лишь Starlette на стероидах): + +* Серьёзно впечатляющая производительность. Это один из самых быстрых фреймворков на Python, наравне с приложениями использующими **NodeJS** или **Go**. +* Поддержка **WebSocket**. +* Фоновые задачи для процессов. +* События запуска и выключения. +* Тестовый клиент построен на библиотеке `requests`. +* **CORS**, GZip, статические файлы, потоковые ответы. +* Поддержка **сессий и cookie**. +* 100% покрытие тестами. +* 100% аннотирование типов в кодовой базе. + +## Особенности и возможности Pydantic + +**FastAPI** основан на Pydantic и полностью совместим с ним. Так что, любой дополнительный код Pydantic, который у вас есть, будет также работать. + +Включая внешние библиотеки, также основанные на Pydantic, такие как: ORM'ы, ODM'ы для баз данных. + +Это также означает, что во многих случаях вы можете передавать тот же объект, который получили из запроса, **непосредственно в базу данных**, так как всё проверяется автоматически. + +И наоборот, во многих случаях вы можете просто передать объект, полученный из базы данных, **непосредственно клиенту**. + +С **FastAPI** вы получаете все возможности **Pydantic** (так как, FastAPI основан на Pydantic, для обработки данных): + +* **Никакой нервотрёпки** : + * Не нужно изучать новых схем в микроязыках. + * Если вы знаете аннотации типов в Python, вы знаете, как использовать Pydantic. +* Прекрасно сочетается с вашими **IDE/linter/мозгом**: + * Потому что структуры данных pydantic - это всего лишь экземпляры классов, определённых вами. Автодополнение, проверка кода, mypy и ваша интуиция - всё будет работать с вашими проверенными данными. +* **Быстродействие**: + * В тестовых замерах Pydantic быстрее, чем все другие проверенные библиотеки. +* Проверка **сложных структур**: + * Использование иерархических моделей Pydantic; `List`, `Dict` и т.п. из модуля `typing` (входит в стандартную библиотеку Python). + * Валидаторы позволяют четко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema. + * У вас могут быть глубоко **вложенные объекты JSON** и все они будут проверены и аннотированы. +* **Расширяемость**: + * Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели, с помощью проверочных декораторов. +* 100% покрытие тестами. diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index 0c2506b87..448e2c707 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -1,50 +1,48 @@ - -{!../../../docs/missing-translation.md!} - -

FastAPI

- FastAPI framework, high performance, easy to learn, fast to code, ready for production + Готовый к внедрению высокопроизводительный фреймворк, простой в изучении и разработке.

- - Build Status + + Test - Coverage + Coverage - Package version + Package version + + + Supported Python versions

--- -**Documentation**: https://fastapi.tiangolo.com +**Документация**: https://fastapi.tiangolo.com -**Source Code**: https://github.com/tiangolo/fastapi +**Исходный код**: https://github.com/tiangolo/fastapi --- -FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints. +FastAPI — это современный, быстрый (высокопроизводительный) веб-фреймворк для создания API используя Python 3.6+, в основе которого лежит стандартная аннотация типов Python. -The key features are: +Ключевые особенности: -* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). +* **Скорость**: Очень высокая производительность, на уровне **NodeJS** и **Go** (благодаря Starlette и Pydantic). [Один из самых быстрых фреймворков Python](#_10). +* **Быстрота разработки**: Увеличьте скорость разработки примерно на 200–300%. * +* **Меньше ошибок**: Сократите примерно на 40% количество ошибок, вызванных человеком (разработчиком). * +* **Интуитивно понятный**: Отличная поддержка редактора. Автозавершение везде. Меньше времени на отладку. +* **Лёгкость**: Разработан так, чтобы его было легко использовать и осваивать. Меньше времени на чтение документации. +* **Краткость**: Сведите к минимуму дублирование кода. Каждый объявленный параметр - определяет несколько функций. Меньше ошибок. +* **Надежность**: Получите готовый к работе код. С автоматической интерактивной документацией. +* **На основе стандартов**: Основан на открытых стандартах API и полностью совместим с ними: OpenAPI (ранее известном как Swagger) и JSON Schema. -* **Fast to code**: Increase the speed to develop features by about 200% to 300%. * -* **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * -* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. -* **Easy**: Designed to be easy to use and learn. Less time reading docs. -* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. -* **Robust**: Get production-ready code. With automatic interactive documentation. -* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. +* оценка на основе тестов внутренней команды разработчиков, создающих производственные приложения. -* estimation based on tests on an internal development team, building production applications. - -## Sponsors +## Спонсоры @@ -59,66 +57,66 @@ The key features are: -Other sponsors +Другие спонсоры -## Opinions +## Отзывы -"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" +"_В последнее время я много где использую **FastAPI**. [...] На самом деле я планирую использовать его для всех **сервисов машинного обучения моей команды в Microsoft**. Некоторые из них интегрируются в основной продукт **Windows**, а некоторые — в продукты **Office**._"
Kabir Khan - Microsoft (ref)
--- -"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" +"_Мы использовали библиотеку **FastAPI** для создания сервера **REST**, к которому можно делать запросы для получения **прогнозов**. [для Ludwig]_"
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
--- -"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" +"_**Netflix** рада объявить о выпуске опенсорсного фреймворка для оркестровки **антикризисного управления**: **Dispatch**! [создана с помощью **FastAPI**]_"
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
--- -"_I’m over the moon excited about **FastAPI**. It’s so fun!_" +"_Я в полном восторге от **FastAPI**. Это так весело!_"
Brian Okken - Python Bytes podcast host (ref)
--- -"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" +"_Честно говоря, то, что вы создали, выглядит очень солидно и отполировано. Во многих смыслах я хотел, чтобы **Hug** был именно таким — это действительно вдохновляет, когда кто-то создаёт такое._"
Timothy Crosley - Hug creator (ref)
--- -"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" +"_Если вы хотите изучить какой-нибудь **современный фреймворк** для создания REST API, ознакомьтесь с **FastAPI** [...] Он быстрый, лёгкий и простой в изучении [...]_" -"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" +"_Мы перешли на **FastAPI** для наших **API** [...] Я думаю, вам тоже понравится [...]_"
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
--- -## **Typer**, the FastAPI of CLIs +## **Typer**, интерфейс командной строки для FastAPI -If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**. +Если вы создаете приложение CLI для использования в терминале вместо веб-API, ознакомьтесь с **Typer**. -**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀 +**Typer** — младший брат FastAPI. И он предназначен для использования в качестве **интерфейса командной строки для FastAPI**. ⌨️ 🚀 -## Requirements +## Зависимости Python 3.6+ -FastAPI stands on the shoulders of giants: +FastAPI стоит на плечах гигантов: -* Starlette for the web parts. -* Pydantic for the data parts. +* Starlette для части связанной с вебом. +* Pydantic для части связанной с данными. -## Installation +## Установка
@@ -130,26 +128,26 @@ $ pip install fastapi
-You will also need an ASGI server, for production such as Uvicorn or Hypercorn. +Вам также понадобится сервер ASGI для производства, такой как Uvicorn или Hypercorn.
```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ```
-## Example +## Пример -### Create it +### Создание -* Create a file `main.py` with: +* Создайте файл `main.py` со следующим содержимым: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,17 +160,17 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ```
-Or use async def... +Или используйте async def... -If your code uses `async` / `await`, use `async def`: +Если ваш код использует `async` / `await`, используйте `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,19 +183,19 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` -**Note**: +**Примечание**: -If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs. +Если вы не знаете, проверьте раздел _"Торопитесь?"_ в документации об `async` и `await`.
-### Run it +### Запуск -Run the server with: +Запустите сервер с помощью:
@@ -214,57 +212,57 @@ INFO: Application startup complete.
-About the command uvicorn main:app --reload... +О команде uvicorn main:app --reload... -The command `uvicorn main:app` refers to: +Команда `uvicorn main:app` относится к: -* `main`: the file `main.py` (the Python "module"). -* `app`: the object created inside of `main.py` with the line `app = FastAPI()`. -* `--reload`: make the server restart after code changes. Only do this for development. +* `main`: файл `main.py` (модуль Python). +* `app`: объект, созданный внутри `main.py` с помощью строки `app = FastAPI()`. +* `--reload`: перезапуск сервера после изменения кода. Делайте это только во время разработки.
-### Check it +### Проверка -Open your browser at http://127.0.0.1:8000/items/5?q=somequery. +Откройте браузер на http://127.0.0.1:8000/items/5?q=somequery. -You will see the JSON response as: +Вы увидите следующий JSON ответ: ```JSON {"item_id": 5, "q": "somequery"} ``` -You already created an API that: +Вы уже создали API, который: -* Receives HTTP requests in the _paths_ `/` and `/items/{item_id}`. -* Both _paths_ take `GET` operations (also known as HTTP _methods_). -* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`. -* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`. +* Получает HTTP-запросы по _путям_ `/` и `/items/{item_id}`. +* И первый и второй _путь_ используют `GET` операции (также известные как HTTP _методы_). +* _путь_ `/items/{item_id}` имеет _параметр пути_ `item_id`, который должен быть `int`. +* _путь_ `/items/{item_id}` имеет необязательный `str` _параметр запроса_ `q`. -### Interactive API docs +### Интерактивная документация по API -Now go to http://127.0.0.1:8000/docs. +Перейдите на http://127.0.0.1:8000/docs. -You will see the automatic interactive API documentation (provided by Swagger UI): +Вы увидите автоматическую интерактивную документацию API (предоставленную Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### Alternative API docs +### Альтернативная документация по API -And now, go to http://127.0.0.1:8000/redoc. +А теперь перейдите на http://127.0.0.1:8000/redoc. -You will see the alternative automatic documentation (provided by ReDoc): +Вы увидите альтернативную автоматическую документацию (предоставленную ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -## Example upgrade +## Пример обновления -Now modify the file `main.py` to receive a body from a `PUT` request. +Теперь измените файл `main.py`, чтобы получить тело ответа из `PUT` запроса. -Declare the body using standard Python types, thanks to Pydantic. +Объявите тело, используя стандартную типизацию Python, спасибо Pydantic. ```Python hl_lines="4 9-12 25-27" -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +273,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +282,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -293,175 +291,173 @@ def update_item(item_id: int, item: Item): return {"item_name": item.name, "item_id": item_id} ``` -The server should reload automatically (because you added `--reload` to the `uvicorn` command above). +Сервер должен перезагрузиться автоматически (потому что вы добавили `--reload` к команде `uvicorn` выше). -### Interactive API docs upgrade +### Интерактивное обновление документации API -Now go to http://127.0.0.1:8000/docs. +Перейдите на http://127.0.0.1:8000/docs. -* The interactive API documentation will be automatically updated, including the new body: +* Интерактивная документация API будет автоматически обновляться, включая новое тело: ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API: +* Нажмите на кнопку "Try it out", это позволит вам заполнить параметры и напрямую взаимодействовать с API: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) -* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen: +* Затем нажмите кнопку "Execute", пользовательский интерфейс свяжется с вашим API, отправит параметры, получит результаты и отобразит их на экране: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) -### Alternative API docs upgrade +### Альтернативное обновление документации API -And now, go to http://127.0.0.1:8000/redoc. +А теперь перейдите на http://127.0.0.1:8000/redoc. -* The alternative documentation will also reflect the new query parameter and body: +* Альтернативная документация также будет отражать новый параметр и тело запроса: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### Recap +### Подведём итоги -In summary, you declare **once** the types of parameters, body, etc. as function parameters. +Таким образом, вы объявляете **один раз** типы параметров, тело и т. д. в качестве параметров функции. -You do that with standard modern Python types. +Вы делаете это испльзуя стандартную современную типизацию Python. -You don't have to learn a new syntax, the methods or classes of a specific library, etc. +Вам не нужно изучать новый синтаксис, методы или классы конкретной библиотеки и т. д. -Just standard **Python 3.6+**. +Только стандартный **Python 3.6+**. -For example, for an `int`: +Например, для `int`: ```Python item_id: int ``` -or for a more complex `Item` model: +или для более сложной модели `Item`: ```Python item: Item ``` -...and with that single declaration you get: +... и с этим единственным объявлением вы получаете: -* Editor support, including: - * Completion. - * Type checks. -* Validation of data: - * Automatic and clear errors when the data is invalid. - * Validation even for deeply nested JSON objects. -* Conversion of input data: coming from the network to Python data and types. Reading from: +* Поддержка редактора, в том числе: + * Автозавершение. + * Проверка типов. +* Валидация данных: + * Автоматические и четкие ошибки, когда данные недействительны. + * Проверка даже для глубоко вложенных объектов JSON. +* Преобразование входных данных: поступающие из сети в объекты Python с соблюдением типов. Чтение из: * JSON. - * Path parameters. - * Query parameters. + * Параметров пути. + * Параметров запроса. * Cookies. - * Headers. - * Forms. - * Files. -* Conversion of output data: converting from Python data and types to network data (as JSON): - * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). - * `datetime` objects. - * `UUID` objects. - * Database models. - * ...and many more. -* Automatic interactive API documentation, including 2 alternative user interfaces: + * Заголовков. + * Форм. + * Файлов. +* Преобразование выходных данных: преобразование объектов Python в данные передаваемые по сети интернет (такие как JSON): + * Преобразование типов Python (`str`, `int`, `float`, `bool`, `list`, и т.д.). + * Объекты `datetime`. + * Объекты `UUID`. + * Модели баз данных. + * ...и многое другое. +* Автоматическая интерактивная документация по API, включая 2 альтернативных пользовательских интерфейса: * Swagger UI. * ReDoc. --- -Coming back to the previous code example, **FastAPI** will: +Возвращаясь к предыдущему примеру кода, **FastAPI** будет: -* Validate that there is an `item_id` in the path for `GET` and `PUT` requests. -* Validate that the `item_id` is of type `int` for `GET` and `PUT` requests. - * If it is not, the client will see a useful, clear error. -* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests. - * As the `q` parameter is declared with `= None`, it is optional. - * Without the `None` it would be required (as is the body in the case with `PUT`). -* For `PUT` requests to `/items/{item_id}`, Read the body as JSON: - * Check that it has a required attribute `name` that should be a `str`. - * Check that it has a required attribute `price` that has to be a `float`. - * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present. - * All this would also work for deeply nested JSON objects. -* Convert from and to JSON automatically. -* Document everything with OpenAPI, that can be used by: - * Interactive documentation systems. - * Automatic client code generation systems, for many languages. -* Provide 2 interactive documentation web interfaces directly. +* Проверять наличие `item_id` в пути для запросов `GET` и `PUT`. +* Проверять, что `item_id` имеет тип `int` для запросов `GET` и `PUT`. + * Если это не так, клиент увидит полезную чёткую ошибку. +* Проверять, есть ли необязательный параметр запроса с именем `q` (например, `http://127.0.0.1:8000/items/foo?q=somequery`) для `GET` запросов. + * Поскольку параметр `q` объявлен с `= None`, он является необязательным. + * Без `None` он был бы необходим (как тело в случае с `PUT`). +* Для `PUT` запросов к `/items/{item_id}` читать тело как JSON: + * Проверять, что у него есть обязательный атрибут `name`, который должен быть `str`. + * Проверять, что у него есть обязательный атрибут `price`, который должен быть `float`. + * Проверять, что у него есть необязательный атрибут `is_offer`, который должен быть `bool`, если он присутствует. + * Все это также будет работать для глубоко вложенных объектов JSON. +* Преобразовывать из и в JSON автоматически. +* Документировать с помощью OpenAPI все, что может быть использовано: + * Системы интерактивной документации. + * Системы автоматической генерации клиентского кода для многих языков. +* Обеспечит 2 интерактивных веб-интерфейса документации напрямую. --- -We just scratched the surface, but you already get the idea of how it all works. +Мы только немного копнули поверхность, но вы уже поняли, как все это работает. -Try changing the line with: +Попробуйте изменить строку с помощью: ```Python return {"item_name": item.name, "item_id": item_id} ``` -...from: +...из: ```Python ... "item_name": item.name ... ``` -...to: +...в: ```Python ... "item_price": item.price ... ``` -...and see how your editor will auto-complete the attributes and know their types: +... и посмотрите, как ваш редактор будет автоматически заполнять атрибуты и узнавать их типы: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -For a more complete example including more features, see the Tutorial - User Guide. +Более полный пример с дополнительными функциями см. в Учебное руководство - Руководство пользователя. -**Spoiler alert**: the tutorial - user guide includes: +**Осторожно, спойлер**: руководство пользователя включает в себя: -* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**. -* How to set **validation constraints** as `maximum_length` or `regex`. -* A very powerful and easy to use **Dependency Injection** system. -* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. -* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). -* Many extra features (thanks to Starlette) as: - * **WebSockets** - * **GraphQL** - * extremely easy tests based on `requests` and `pytest` +* Объявление **параметров** из других мест, таких как: **заголовки**, **cookies**, **поля формы** и **файлы**. +* Как установить **ограничительные проверки** такие как `maximum_length` или `regex`. +* Очень мощная и простая в использовании система **внедрения зависимостей**. +* Безопасность и аутентификация, включая поддержку **OAuth2** с **токенами JWT** и **HTTP Basic** аутентификацию. +* Более продвинутые (но столь же простые) методы объявления **глубоко вложенных моделей JSON** (спасибо Pydantic). +* **GraphQL** интеграция с Strawberry и другими библиотеками. +* Множество дополнительных функций (благодаря Starlette), таких как: + * **Веб-сокеты** + * очень простые тесты на основе `requests` и `pytest` * **CORS** - * **Cookie Sessions** - * ...and more. + * **Cookie сеансы(сессии)** + * ...и многое другое. -## Performance +## Производительность -Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) +Независимые тесты TechEmpower показывают приложения **FastAPI**, работающие под управлением Uvicorn, как один из самых быстрых доступных фреймворков Python, уступающий только самим Starlette и Uvicorn (используемых внутри FastAPI). (*) -To understand more about it, see the section Benchmarks. +Чтобы узнать больше об этом, см. раздел Тесты производительности. -## Optional Dependencies +## Необязательные зависимости -Used by Pydantic: +Используется Pydantic: -* ujson - for faster JSON "parsing". -* email_validator - for email validation. +* ujson - для более быстрого JSON "парсинга". +* email_validator - для проверки электронной почты. -Used by Starlette: +Используется Starlette: -* requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. -* jinja2 - Required if you want to use the default template configuration. -* python-multipart - Required if you want to support form "parsing", with `request.form()`. -* itsdangerous - Required for `SessionMiddleware` support. -* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). -* graphene - Required for `GraphQLApp` support. -* ujson - Required if you want to use `UJSONResponse`. +* requests - Обязательно, если вы хотите использовать `TestClient`. +* jinja2 - Обязательно, если вы хотите использовать конфигурацию шаблона по умолчанию. +* python-multipart - Обязательно, если вы хотите поддерживать форму "парсинга" с помощью `request.form()`. +* itsdangerous - Обязательно, для поддержки `SessionMiddleware`. +* pyyaml - Обязательно, для поддержки `SchemaGenerator` Starlette (возможно, вам это не нужно с FastAPI). +* ujson - Обязательно, если вы хотите использовать `UJSONResponse`. -Used by FastAPI / Starlette: +Используется FastAPI / Starlette: -* uvicorn - for the server that loads and serves your application. -* orjson - Required if you want to use `ORJSONResponse`. +* uvicorn - сервер, который загружает и обслуживает ваше приложение. +* orjson - Обязательно, если вы хотите использовать `ORJSONResponse`. -You can install all of these with `pip install fastapi[all]`. +Вы можете установить все это с помощью `pip install "fastapi[all]"`. -## License +## Лицензия -This project is licensed under the terms of the MIT license. +Этот проект распространяется на условиях лицензии MIT. diff --git a/docs/ru/docs/python-types.md b/docs/ru/docs/python-types.md index 99670363c..7523083c8 100644 --- a/docs/ru/docs/python-types.md +++ b/docs/ru/docs/python-types.md @@ -1,6 +1,6 @@ # Введение в аннотации типов Python -Python имеет поддержку необязательных аннотаций типов. +Python имеет поддержку необязательных аннотаций типов. **Аннотации типов** являются специальным синтаксисом, который позволяет определять тип переменной. diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md new file mode 100644 index 000000000..e608f6c8f --- /dev/null +++ b/docs/ru/docs/tutorial/background-tasks.md @@ -0,0 +1,102 @@ +# Фоновые задачи + +Вы можете создавать фоновые задачи, которые будут выполнятся *после* возвращения ответа сервером. + +Это может быть полезно для функций, которые должны выполниться после получения запроса, но ожидание их выполнения необязательно для пользователя. + +К примеру: + +* Отправка писем на почту после выполнения каких-либо действий: + * Т.к. соединение с почтовым сервером и отправка письма идут достаточно "долго" (несколько секунд), вы можете отправить ответ пользователю, а отправку письма выполнить в фоне. +* Обработка данных: + * К примеру, если вы получаете файл, который должен пройти через медленный процесс, вы можете отправить ответ "Accepted" (HTTP 202) и отправить работу с файлом в фон. + +## Использование класса `BackgroundTasks` + +Сначала импортируйте `BackgroundTasks`, потом добавьте в функцию параметр с типом `BackgroundTasks`: + +```Python hl_lines="1 13" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +**FastAPI** создаст объект класса `BackgroundTasks` для вас и запишет его в параметр. + +## Создание функции для фоновой задачи + +Создайте функцию, которую хотите запустить в фоне. + +Это совершенно обычная функция, которая может принимать параметры. + +Она может быть как асинхронной `async def`, так и обычной `def` функцией, **FastAPI** знает, как правильно ее выполнить. + +В нашем примере фоновая задача будет вести запись в файл (симулируя отправку письма). + +Так как операция записи не использует `async` и `await`, мы определим ее как обычную `def`: + +```Python hl_lines="6-9" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +## Добавление фоновой задачи + +Внутри функции вызовите метод `.add_task()` у объекта *background tasks* и передайте ему функцию, которую хотите выполнить в фоне: + +```Python hl_lines="14" +{!../../../docs_src/background_tasks/tutorial001.py!} +``` + +`.add_task()` принимает следующие аргументы: + +* Функцию, которая будет выполнена в фоне (`write_notification`). Обратите внимание, что передается объект функции, без скобок. +* Любое упорядоченное количество аргументов, которые принимает функция (`email`). +* Любое количество именованных аргументов, которые принимает функция (`message="some notification"`). + +## Встраивание зависимостей + +Класс `BackgroundTasks` также работает с системой встраивания зависимостей, вы можете определить `BackgroundTasks` на разных уровнях: как параметр функции, как завимость, как подзависимость и так далее. + +**FastAPI** знает, что нужно сделать в каждом случае и как переиспользовать тот же объект `BackgroundTasks`, так чтобы все фоновые задачи собрались и запустились вместе в фоне: + +=== "Python 3.6 и выше" + + ```Python hl_lines="13 15 22 25" + {!> ../../../docs_src/background_tasks/tutorial002.py!} + ``` + +=== "Python 3.10 и выше" + + ```Python hl_lines="11 13 20 23" + {!> ../../../docs_src/background_tasks/tutorial002_py310.py!} + ``` + +В этом примере сообщения будут записаны в `log.txt` *после* того, как ответ сервера был отправлен. + +Если бы в запросе была очередь `q`, она бы первой записалась в `log.txt` фоновой задачей (потому что вызывается в зависимости `get_query`). + +После другая фоновая задача, которая была сгенерирована в функции, запишет сообщение из параметра `email`. + +## Технические детали + +Класс `BackgroundTasks` основан на `starlette.background`. + +Он интегрирован в FastAPI, так что вы можете импортировать его прямо из `fastapi` и избежать случайного импорта `BackgroundTask` (без `s` на конце) из `starlette.background`. + +При использовании `BackgroundTasks` (а не `BackgroundTask`), вам достаточно только определить параметр функции с типом `BackgroundTasks` и **FastAPI** сделает все за вас, также как при использовании объекта `Request`. + +Вы все равно можете использовать `BackgroundTask` из `starlette` в FastAPI, но вам придется самостоятельно создавать объект фоновой задачи и вручную обработать `Response` внутри него. + +Вы можете подробнее изучить его в Официальной документации Starlette для BackgroundTasks. + +## Предостережение + +Если вам нужно выполнить тяжелые вычисления в фоне, которым необязательно быть запущенными в одном процессе с приложением **FastAPI** (к примеру, вам не нужны обрабатываемые переменные или вы не хотите делиться памятью процесса и т.д.), вы можете использовать более серьезные инструменты, такие как Celery. + +Их тяжелее настраивать, также им нужен брокер сообщений наподобие RabbitMQ или Redis, но зато они позволяют вам запускать фоновые задачи в нескольких процессах и даже на нескольких серверах. + +Для примера, посмотрите [Project Generators](../project-generation.md){.internal-link target=_blank}, там есть проект с уже настроенным Celery. + +Но если вам нужен доступ к общим переменным и объектам вашего **FastAPI** приложения или вам нужно выполнять простые фоновые задачи (наподобие отправки письма из примера) вы можете просто использовать `BackgroundTasks`. + +## Резюме + +Для создания фоновых задач вам необходимо импортировать `BackgroundTasks` и добавить его в функцию, как параметр с типом `BackgroundTasks`. diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml index 6e17c287e..381775ac6 100644 --- a/docs/ru/mkdocs.yml +++ b/docs/ru/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,18 +42,30 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ +- features.md +- python-types.md +- Учебник - руководство пользователя: + - tutorial/background-tasks.md +- external-links.md +- async.md +- Развёртывание: + - deployment/versions.md markdown_extensions: - toc: permalink: true @@ -69,6 +83,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +113,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +127,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +137,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/sq/docs/index.md b/docs/sq/docs/index.md index 95fb7ae21..2b64003fe 100644 --- a/docs/sq/docs/index.md +++ b/docs/sq/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -149,7 +149,7 @@ $ pip install uvicorn[standard] * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,7 +162,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,7 +185,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -264,7 +264,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 Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +275,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +284,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. diff --git a/docs/sq/mkdocs.yml b/docs/sq/mkdocs.yml index d9c3dad4c..b07f3bc63 100644 --- a/docs/sq/mkdocs.yml +++ b/docs/sq/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -69,6 +75,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +105,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +119,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +129,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/sv/docs/index.md b/docs/sv/docs/index.md new file mode 100644 index 000000000..fd52f994c --- /dev/null +++ b/docs/sv/docs/index.md @@ -0,0 +1,468 @@ + +{!../../../docs/missing-translation.md!} + + +

+ FastAPI +

+

+ FastAPI framework, high performance, easy to learn, fast to code, ready for production +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**Documentation**: https://fastapi.tiangolo.com + +**Source Code**: https://github.com/tiangolo/fastapi + +--- + +FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints. + +The key features are: + +* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic). [One of the fastest Python frameworks available](#performance). + +* **Fast to code**: Increase the speed to develop features by about 200% to 300%. * +* **Fewer bugs**: Reduce about 40% of human (developer) induced errors. * +* **Intuitive**: Great editor support. Completion everywhere. Less time debugging. +* **Easy**: Designed to be easy to use and learn. Less time reading docs. +* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. +* **Robust**: Get production-ready code. With automatic interactive documentation. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. + +* estimation based on tests on an internal development team, building production applications. + +## Sponsors + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +Other sponsors + +## Opinions + +"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" + +
Kabir Khan - Microsoft (ref)
+ +--- + +"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" + +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +"_I’m over the moon excited about **FastAPI**. It’s so fun!_" + +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" + +
Timothy Crosley - Hug creator (ref)
+ +--- + +"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" + +"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, the FastAPI of CLIs + + + +If you are building a CLI app to be used in the terminal instead of a web API, check out **Typer**. + +**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀 + +## Requirements + +Python 3.6+ + +FastAPI stands on the shoulders of giants: + +* Starlette for the web parts. +* Pydantic for the data parts. + +## Installation + +
+ +```console +$ pip install fastapi + +---> 100% +``` + +
+ +You will also need an ASGI server, for production such as Uvicorn or Hypercorn. + +
+ +```console +$ pip install "uvicorn[standard]" + +---> 100% +``` + +
+ +## Example + +### Create it + +* Create a file `main.py` with: + +```Python +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+Or use async def... + +If your code uses `async` / `await`, use `async def`: + +```Python hl_lines="9 14" +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +**Note**: + +If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs. + +
+ +### Run it + +Run the server with: + +
+ +```console +$ uvicorn main:app --reload + +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. +``` + +
+ +
+About the command uvicorn main:app --reload... + +The command `uvicorn main:app` refers to: + +* `main`: the file `main.py` (the Python "module"). +* `app`: the object created inside of `main.py` with the line `app = FastAPI()`. +* `--reload`: make the server restart after code changes. Only do this for development. + +
+ +### Check it + +Open your browser at http://127.0.0.1:8000/items/5?q=somequery. + +You will see the JSON response as: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +You already created an API that: + +* Receives HTTP requests in the _paths_ `/` and `/items/{item_id}`. +* Both _paths_ take `GET` operations (also known as HTTP _methods_). +* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`. +* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`. + +### Interactive API docs + +Now go to http://127.0.0.1:8000/docs. + +You will see the automatic interactive API documentation (provided by Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Alternative API docs + +And now, go to http://127.0.0.1:8000/redoc. + +You will see the alternative automatic documentation (provided by ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## Example upgrade + +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 + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Union[bool, None] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +The server should reload automatically (because you added `--reload` to the `uvicorn` command above). + +### Interactive API docs upgrade + +Now go to http://127.0.0.1:8000/docs. + +* The interactive API documentation will be automatically updated, including the new body: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### Alternative API docs upgrade + +And now, go to http://127.0.0.1:8000/redoc. + +* The alternative documentation will also reflect the new query parameter and body: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Recap + +In summary, you declare **once** the types of parameters, body, etc. as function parameters. + +You do that with standard modern Python types. + +You don't have to learn a new syntax, the methods or classes of a specific library, etc. + +Just standard **Python 3.6+**. + +For example, for an `int`: + +```Python +item_id: int +``` + +or for a more complex `Item` model: + +```Python +item: Item +``` + +...and with that single declaration you get: + +* Editor support, including: + * Completion. + * Type checks. +* Validation of data: + * Automatic and clear errors when the data is invalid. + * Validation even for deeply nested JSON objects. +* Conversion of input data: coming from the network to Python data and types. Reading from: + * JSON. + * Path parameters. + * Query parameters. + * Cookies. + * Headers. + * Forms. + * Files. +* Conversion of output data: converting from Python data and types to network data (as JSON): + * Convert Python types (`str`, `int`, `float`, `bool`, `list`, etc). + * `datetime` objects. + * `UUID` objects. + * Database models. + * ...and many more. +* Automatic interactive API documentation, including 2 alternative user interfaces: + * Swagger UI. + * ReDoc. + +--- + +Coming back to the previous code example, **FastAPI** will: + +* Validate that there is an `item_id` in the path for `GET` and `PUT` requests. +* Validate that the `item_id` is of type `int` for `GET` and `PUT` requests. + * If it is not, the client will see a useful, clear error. +* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests. + * As the `q` parameter is declared with `= None`, it is optional. + * Without the `None` it would be required (as is the body in the case with `PUT`). +* For `PUT` requests to `/items/{item_id}`, Read the body as JSON: + * Check that it has a required attribute `name` that should be a `str`. + * Check that it has a required attribute `price` that has to be a `float`. + * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present. + * All this would also work for deeply nested JSON objects. +* Convert from and to JSON automatically. +* Document everything with OpenAPI, that can be used by: + * Interactive documentation systems. + * Automatic client code generation systems, for many languages. +* Provide 2 interactive documentation web interfaces directly. + +--- + +We just scratched the surface, but you already get the idea of how it all works. + +Try changing the line with: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...from: + +```Python + ... "item_name": item.name ... +``` + +...to: + +```Python + ... "item_price": item.price ... +``` + +...and see how your editor will auto-complete the attributes and know their types: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +For a more complete example including more features, see the Tutorial - User Guide. + +**Spoiler alert**: the tutorial - user guide includes: + +* Declaration of **parameters** from other different places as: **headers**, **cookies**, **form fields** and **files**. +* How to set **validation constraints** as `maximum_length` or `regex`. +* A very powerful and easy to use **Dependency Injection** system. +* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth. +* More advanced (but equally easy) techniques for declaring **deeply nested JSON models** (thanks to Pydantic). +* **GraphQL** integration with Strawberry and other libraries. +* Many extra features (thanks to Starlette) as: + * **WebSockets** + * extremely easy tests based on `requests` and `pytest` + * **CORS** + * **Cookie Sessions** + * ...and more. + +## Performance + +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) + +To understand more about it, see the section Benchmarks. + +## Optional Dependencies + +Used by Pydantic: + +* ujson - for faster JSON "parsing". +* email_validator - for email validation. + +Used by Starlette: + +* requests - Required if you want to use the `TestClient`. +* jinja2 - Required if you want to use the default template configuration. +* python-multipart - Required if you want to support form "parsing", with `request.form()`. +* itsdangerous - Required for `SessionMiddleware` support. +* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). +* ujson - Required if you want to use `UJSONResponse`. + +Used by FastAPI / Starlette: + +* uvicorn - for the server that loads and serves your application. +* orjson - Required if you want to use `ORJSONResponse`. + +You can install all of these with `pip install "fastapi[all]"`. + +## License + +This project is licensed under the terms of the MIT license. diff --git a/docs/sv/mkdocs.yml b/docs/sv/mkdocs.yml new file mode 100644 index 000000000..3332d232d --- /dev/null +++ b/docs/sv/mkdocs.yml @@ -0,0 +1,145 @@ +site_name: FastAPI +site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production +site_url: https://fastapi.tiangolo.com/sv/ +theme: + name: material + custom_dir: overrides + palette: + - media: '(prefers-color-scheme: light)' + scheme: default + primary: teal + accent: amber + toggle: + icon: material/lightbulb + name: Switch to light mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + primary: teal + accent: amber + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + features: + - search.suggest + - search.highlight + - content.tabs.link + icon: + repo: fontawesome/brands/github-alt + logo: https://fastapi.tiangolo.com/img/icon-white.svg + favicon: https://fastapi.tiangolo.com/img/favicon.png + language: sv +repo_name: tiangolo/fastapi +repo_url: https://github.com/tiangolo/fastapi +edit_uri: '' +plugins: +- search +- markdownextradata: + data: data +nav: +- FastAPI: index.md +- Languages: + - en: / + - az: /az/ + - de: /de/ + - es: /es/ + - fa: /fa/ + - fr: /fr/ + - he: /he/ + - id: /id/ + - it: /it/ + - ja: /ja/ + - ko: /ko/ + - nl: /nl/ + - pl: /pl/ + - pt: /pt/ + - ru: /ru/ + - sq: /sq/ + - sv: /sv/ + - tr: /tr/ + - uk: /uk/ + - zh: /zh/ +markdown_extensions: +- toc: + permalink: true +- markdown.extensions.codehilite: + guess_lang: false +- mdx_include: + base_path: docs +- admonition +- codehilite +- extra +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format '' +- pymdownx.tabbed: + alternate_style: true +- attr_list +- md_in_html +extra: + analytics: + provider: google + property: UA-133183413-1 + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/tiangolo/fastapi + - icon: fontawesome/brands/discord + link: https://discord.gg/VQjSZaeJmf + - icon: fontawesome/brands/twitter + link: https://twitter.com/fastapi + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/tiangolo + - icon: fontawesome/brands/dev + link: https://dev.to/tiangolo + - icon: fontawesome/brands/medium + link: https://medium.com/@tiangolo + - icon: fontawesome/solid/globe + link: https://tiangolo.com + alternate: + - link: / + name: en - English + - link: /az/ + name: az + - link: /de/ + name: de + - link: /es/ + name: es - español + - link: /fa/ + name: fa + - link: /fr/ + name: fr - français + - link: /he/ + name: he + - link: /id/ + name: id + - link: /it/ + name: it - italiano + - link: /ja/ + name: ja - 日本語 + - link: /ko/ + name: ko - 한국어 + - link: /nl/ + name: nl + - link: /pl/ + name: pl + - link: /pt/ + name: pt - português + - link: /ru/ + name: ru - русский язык + - link: /sq/ + name: sq - shqip + - link: /sv/ + name: sv - svenska + - link: /tr/ + name: tr - Türkçe + - link: /uk/ + name: uk - українська мова + - link: /zh/ + name: zh - 汉语 +extra_css: +- https://fastapi.tiangolo.com/css/termynal.css +- https://fastapi.tiangolo.com/css/custom.css +extra_javascript: +- https://fastapi.tiangolo.com/js/termynal.js +- https://fastapi.tiangolo.com/js/custom.js diff --git a/docs/sv/overrides/.gitignore b/docs/sv/overrides/.gitignore new file mode 100644 index 000000000..e69de29bb diff --git a/docs/tr/docs/features.md b/docs/tr/docs/features.md index c06c27c16..0bcda4e9c 100644 --- a/docs/tr/docs/features.md +++ b/docs/tr/docs/features.md @@ -6,7 +6,7 @@ ### Açık standartları temel alır -* API oluşturma işlemlerinde OpenAPI buna path operasyonları parametreleri, body talebi, güvenlik gibi şeyler dahil olmak üzere deklare bunların deklare edilmesi. +* API oluşturma işlemlerinde OpenAPI buna path operasyonları parametreleri, body talebi, güvenlik gibi şeyler dahil olmak üzere deklare bunların deklare edilmesi. * Otomatik olarak data modelinin JSON Schema ile beraber dokümante edilmesi (OpenAPI'n kendisi zaten JSON Schema'ya dayanıyor). * Titiz bir çalışmanın sonucunda yukarıdaki standartlara uygun bir framework oluşturduk. Standartları pastanın üzerine sonradan eklenmiş bir çilek olarak görmedik. * Ayrıca bu bir çok dilde kullanılabilecek **client code generator** kullanımına da izin veriyor. @@ -74,7 +74,7 @@ my_second_user: User = User(**second_user_data) ### Editor desteği -Bütün framework kullanılması kolay ve sezgileri güçlü olması için tasarlandı, verilen bütün kararlar geliştiricilere en iyi geliştirme deneyimini yaşatmak üzere, bir çok editör üzerinde test edildi. +Bütün framework kullanılması kolay ve sezgileri güçlü olması için tasarlandı, verilen bütün kararlar geliştiricilere en iyi geliştirme deneyimini yaşatmak üzere, bir çok editör üzerinde test edildi. Son yapılan Python geliştiricileri anketinde, açık ara en çok kullanılan özellik "oto-tamamlama" idi.. @@ -135,7 +135,7 @@ Bütün güvenlik şemaları OpenAPI'da tanımlanmış durumda, kapsadıkları: Bütün güvenlik özellikleri Starlette'den geliyor (**session cookies'de** dahil olmak üzere). -Bütün hepsi tekrardan kullanılabilir aletler ve bileşenler olarak, kolayca sistemlerinize, data depolarınıza, ilişkisel ve NoSQL databaselerinize entegre edebileceğiniz şekilde yapıldı. +Bütün hepsi tekrardan kullanılabilir aletler ve bileşenler olarak, kolayca sistemlerinize, data depolarınıza, ilişkisel ve NoSQL databaselerinize entegre edebileceğiniz şekilde yapıldı. ### Dependency injection @@ -198,7 +198,7 @@ Aynı şekilde, databaseden gelen objeyi de **direkt olarak isteğe** de tamamiy * Kullandığın geliştirme araçları ile iyi çalışır **IDE/linter/brain**: * Pydantic'in veri yapıları aslında sadece senin tanımladığın classlar; Bu yüzden doğrulanmış dataların ile otomatik tamamlama, linting ve mypy'ı kullanarak sorunsuz bir şekilde çalışabilirsin * **Hızlı**: - * Benchmarklarda, Pydantic'in diğer bütün test edilmiş bütün kütüphanelerden daha hızlı. + * Benchmarklarda, Pydantic'in diğer bütün test edilmiş bütün kütüphanelerden daha hızlı. * **En kompleks** yapıları bile doğrula: * Hiyerarşik Pydantic modellerinin kullanımı ile beraber, Python `typing`’s `List` and `Dict`, vs gibi şeyleri doğrula. * Doğrulayıcılar en kompleks data şemalarının bile temiz ve kolay bir şekilde tanımlanmasına izin veriyor, ve hepsi JSON şeması olarak dokümante ediliyor @@ -206,4 +206,3 @@ Aynı şekilde, databaseden gelen objeyi de **direkt olarak isteğe** de tamamiy * **Genişletilebilir**: * Pydantic özelleştirilmiş data tiplerinin tanımlanmasının yapılmasına izin veriyor ayrıca validator decoratorü ile senin doğrulamaları genişletip, kendi doğrulayıcılarını yazmana izin veriyor. * 100% test kapsayıcılığı. - diff --git a/docs/tr/docs/index.md b/docs/tr/docs/index.md index 88660f7eb..0d5337c87 100644 --- a/docs/tr/docs/index.md +++ b/docs/tr/docs/index.md @@ -28,7 +28,7 @@ --- -FastAPI, Python 3.6+'nın standart type hintlerine dayanan modern ve hızlı (yüksek performanslı) API'lar oluşturmak için kullanılabilecek web framework'ü. +FastAPI, Python 3.6+'nın standart type hintlerine dayanan modern ve hızlı (yüksek performanslı) API'lar oluşturmak için kullanılabilecek web framework'ü. Ana özellikleri: @@ -143,7 +143,7 @@ Uygulamanı kullanılabilir hale getirmek için ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -157,7 +157,7 @@ $ pip install uvicorn[standard] * `main.py` adında bir dosya oluştur : ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -170,7 +170,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -180,7 +180,7 @@ def read_item(item_id: int, q: Optional[str] = None): Eğer kodunda `async` / `await` var ise, `async def` kullan: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -193,7 +193,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -272,7 +272,7 @@ Senin için alternatif olarak (requests - Eğer `TestClient` kullanmak istiyorsan gerekli. -* aiofiles - `FileResponse` ya da `StaticFiles` kullanmak istiyorsan gerekli. * jinja2 - Eğer kendine ait template konfigürasyonu oluşturmak istiyorsan gerekli * python-multipart - Form kullanmak istiyorsan gerekli ("dönüşümü"). * itsdangerous - `SessionMiddleware` desteği için gerekli. diff --git a/docs/tr/docs/python-types.md b/docs/tr/docs/python-types.md index 7e46bd031..3b9ab9050 100644 --- a/docs/tr/docs/python-types.md +++ b/docs/tr/docs/python-types.md @@ -29,7 +29,7 @@ Programın çıktısı: John Doe ``` -Fonksiyon sırayla şunları yapar: +Fonksiyon sırayla şunları yapar: * `first_name` ve `last_name` değerlerini alır. * `title()` ile değişkenlerin ilk karakterlerini büyütür. diff --git a/docs/tr/mkdocs.yml b/docs/tr/mkdocs.yml index f6ed7f5b9..e29d25936 100644 --- a/docs/tr/mkdocs.yml +++ b/docs/tr/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -72,6 +78,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -100,8 +108,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -110,6 +122,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -118,6 +132,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/uk/docs/index.md b/docs/uk/docs/index.md index 95fb7ae21..2b64003fe 100644 --- a/docs/uk/docs/index.md +++ b/docs/uk/docs/index.md @@ -135,7 +135,7 @@ You will also need an ASGI server, for production such as ```console -$ pip install uvicorn[standard] +$ pip install "uvicorn[standard]" ---> 100% ``` @@ -149,7 +149,7 @@ $ pip install uvicorn[standard] * Create a file `main.py` with: ```Python -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -162,7 +162,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -172,7 +172,7 @@ def read_item(item_id: int, q: Optional[str] = None): If your code uses `async` / `await`, use `async def`: ```Python hl_lines="9 14" -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -185,7 +185,7 @@ async def read_root(): @app.get("/items/{item_id}") -async def read_item(item_id: int, q: Optional[str] = None): +async def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} ``` @@ -264,7 +264,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 Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -275,7 +275,7 @@ app = FastAPI() class Item(BaseModel): name: str price: float - is_offer: Optional[bool] = None + is_offer: Union[bool, None] = None @app.get("/") @@ -284,7 +284,7 @@ def read_root(): @app.get("/items/{item_id}") -def read_item(item_id: int, q: Optional[str] = None): +def read_item(item_id: int, q: Union[str, None] = None): return {"item_id": item_id, "q": q} @@ -321,7 +321,7 @@ And now, go to requests - Required if you want to use the `TestClient`. -* aiofiles - Required if you want to use `FileResponse` or `StaticFiles`. * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. diff --git a/docs/uk/mkdocs.yml b/docs/uk/mkdocs.yml index d0de8cc0e..711328771 100644 --- a/docs/uk/mkdocs.yml +++ b/docs/uk/mkdocs.yml @@ -5,13 +5,15 @@ theme: name: material custom_dir: overrides palette: - - scheme: default + - media: '(prefers-color-scheme: light)' + scheme: default primary: teal accent: amber toggle: icon: material/lightbulb name: Switch to light mode - - scheme: slate + - media: '(prefers-color-scheme: dark)' + scheme: slate primary: teal accent: amber toggle: @@ -40,15 +42,19 @@ nav: - az: /az/ - de: /de/ - es: /es/ + - fa: /fa/ - fr: /fr/ + - he: /he/ - id: /id/ - it: /it/ - ja: /ja/ - ko: /ko/ + - nl: /nl/ - pl: /pl/ - pt: /pt/ - ru: /ru/ - sq: /sq/ + - sv: /sv/ - tr: /tr/ - uk: /uk/ - zh: /zh/ @@ -69,6 +75,8 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.tabbed: alternate_style: true +- attr_list +- md_in_html extra: analytics: provider: google @@ -97,8 +105,12 @@ extra: name: de - link: /es/ name: es - español + - link: /fa/ + name: fa - link: /fr/ name: fr - français + - link: /he/ + name: he - link: /id/ name: id - link: /it/ @@ -107,6 +119,8 @@ extra: name: ja - 日本語 - link: /ko/ name: ko - 한국어 + - link: /nl/ + name: nl - link: /pl/ name: pl - link: /pt/ @@ -115,6 +129,8 @@ extra: name: ru - русский язык - link: /sq/ name: sq - shqip + - link: /sv/ + name: sv - svenska - link: /tr/ name: tr - Türkçe - link: /uk/ diff --git a/docs/zh/docs/advanced/additional-status-codes.md b/docs/zh/docs/advanced/additional-status-codes.md index 1cb724f1d..54ec9775b 100644 --- a/docs/zh/docs/advanced/additional-status-codes.md +++ b/docs/zh/docs/advanced/additional-status-codes.md @@ -14,7 +14,7 @@ 要实现它，导入 `JSONResponse`，然后在其中直接返回你的内容，并将 `status_code` 设置为为你要的值。 -```Python hl_lines="2 19" +```Python hl_lines="4 25" {!../../../docs_src/additional_status_codes/tutorial001.py!} ``` @@ -22,7 +22,7 @@ 当你直接返回一个像上面例子中的 `Response` 对象时，它会直接返回。 FastAPI 不会用模型等对该响应进行序列化。 - + 确保其中有你想要的数据，且返回的值为合法的 JSON（如果你使用 `JSONResponse` 的话）。 !!! note "技术细节" diff --git a/docs/zh/docs/advanced/custom-response.md b/docs/zh/docs/advanced/custom-response.md index 5f1a74e9e..155ce2882 100644 --- a/docs/zh/docs/advanced/custom-response.md +++ b/docs/zh/docs/advanced/custom-response.md @@ -60,7 +60,7 @@ 正如你在 [直接返回响应](response-directly.md){.internal-link target=_blank} 中了解到的，你也可以通过直接返回响应在 *路径操作* 中直接重载响应。 和上面一样的例子，返回一个 `HTMLResponse` 看起来可能是这样： - + ```Python hl_lines="2 7 19" {!../../../docs_src/custom_response/tutorial003.py!} ``` diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md new file mode 100644 index 000000000..3e53c5319 --- /dev/null +++ b/docs/zh/docs/advanced/response-cookies.md @@ -0,0 +1,47 @@ +# 响应Cookies + +## 使用 `Response` 参数 + +你可以在 *路径函数* 中定义一个类型为 `Response`的参数，这样你就可以在这个临时响应对象中设置cookie了。 + +```Python hl_lines="1 8-9" +{!../../../docs_src/response_cookies/tutorial002.py!} +``` + +而且你还可以根据你的需要响应不同的对象，比如常用的 `dict`，数据库model等。 + +如果你定义了 `response_model`，程序会自动根据`response_model`来过滤和转换你响应的对象。 + +**FastAPI** 会使用这个 *临时* 响应对象去装在这些cookies信息 (同样还有headers和状态码等信息), 最终会将这些信息和通过`response_model`转化过的数据合并到最终的响应里。 + +你也可以在depend中定义`Response`参数，并设置cookie和header。 + +## 直接响应 `Response` + +你还可以在直接响应`Response`时直接创建cookies。 + +你可以参考[Return a Response Directly](response-directly.md){.internal-link target=_blank}来创建response + +然后设置Cookies，并返回： + +```Python hl_lines="10-12" +{!../../../docs_src/response_cookies/tutorial001.py!} +``` + +!!! tip + 需要注意，如果你直接反馈一个response对象，而不是使用`Response`入参，FastAPI则会直接反馈你封装的response对象。 + + 所以你需要确保你响应数据类型的正确性，如：你可以使用`JSONResponse`来兼容JSON的场景。 + + 同时，你也应当仅反馈通过`response_model`过滤过的数据。 + +### 更多信息 + +!!! note "技术细节" + 你也可以使用`from starlette.responses import Response` 或者 `from starlette.responses import JSONResponse`。 + + 为了方便开发者，**FastAPI** 封装了相同数据类型，如`starlette.responses` 和 `fastapi.responses`。不过大部分response对象都是直接引用自Starlette。 + + 因为`Response`对象可以非常便捷的设置headers和cookies，所以 **FastAPI** 同时也封装了`fastapi.Response`。 + +如果你想查看所有可用的参数和选项，可以参考 Starlette帮助文档 diff --git a/docs/zh/docs/advanced/response-directly.md b/docs/zh/docs/advanced/response-directly.md index 05926a9c8..797a878eb 100644 --- a/docs/zh/docs/advanced/response-directly.md +++ b/docs/zh/docs/advanced/response-directly.md @@ -10,7 +10,7 @@ 直接返回响应可能会有用处，比如返回自定义的响应头和 cookies。 -## 返回 `Response` +## 返回 `Response` 事实上，你可以返回任意 `Response` 或者任意 `Response` 的子类。 @@ -62,4 +62,3 @@ 但是你仍可以参考 [OpenApI 中的额外响应](additional-responses.md){.internal-link target=_blank} 给响应编写文档。 在后续的章节中你可以了解到如何使用/声明这些自定义的 `Response` 的同时还保留自动化的数据转换和文档等。 - diff --git a/docs/zh/docs/benchmarks.md b/docs/zh/docs/benchmarks.md index c133d51b7..8991c72cd 100644 --- a/docs/zh/docs/benchmarks.md +++ b/docs/zh/docs/benchmarks.md @@ -22,7 +22,7 @@ * 具有最佳性能，因为除了服务器本身外，它没有太多额外的代码。 * 您不会直接在 Uvicorn 中编写应用程序。这意味着您的代码至少必须包含 Starlette（或 **FastAPI**）提供的代码。如果您这样做了（即直接在 Uvicorn 中编写应用程序），最终的应用程序会和使用了框架并且最小化了应用代码和 bug 的情况具有相同的性能损耗。 * 如果要对比与 Uvicorn 对标的服务器，请将其与 Daphne，Hypercorn，uWSGI等应用服务器进行比较。 -* **Starlette**: +* **Starlette**: * 在 Uvicorn 后使用 Starlette，性能会略有下降。实际上，Starlette 使用 Uvicorn运行。因此，由于必须执行更多的代码，它只会比 Uvicorn 更慢。 * 但它为您提供了构建简单的网络程序的工具，并具有基于路径的路由等功能。 * 如果想对比与 Starlette 对标的开发框架，请将其与 Sanic，Flask，Django 等网络框架（或微框架）进行比较。 diff --git a/docs/zh/docs/contributing.md b/docs/zh/docs/contributing.md index 402668c47..95500d12b 100644 --- a/docs/zh/docs/contributing.md +++ b/docs/zh/docs/contributing.md @@ -497,4 +497,4 @@ $ bash scripts/test-cov-html.sh
-该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。 +该命令生成了一个 `./htmlcov/` 目录，如果你在浏览器中打开 `./htmlcov/index.html` 文件，你可以交互式地浏览被测试所覆盖的代码区块，并注意是否缺少了任何区块。 diff --git a/docs/zh/docs/fastapi-people.md b/docs/zh/docs/fastapi-people.md index 75651592d..5d7b0923f 100644 --- a/docs/zh/docs/fastapi-people.md +++ b/docs/zh/docs/fastapi-people.md @@ -114,6 +114,8 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋 他们主要通过GitHub Sponsors支持我在 **FastAPI** (和其他项目)的工作。 +{% if sponsors %} + {% if sponsors.gold %} ### 金牌赞助商 @@ -141,6 +143,8 @@ FastAPI 有一个非常棒的社区，它欢迎来自各个领域和背景的朋 {% endfor %} {% endif %} +{% endif %} + ### 个人赞助 {% if github_sponsors %} diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md index 4752947a3..fefe4b197 100644 --- a/docs/zh/docs/features.md +++ b/docs/zh/docs/features.md @@ -193,9 +193,9 @@ FastAPI 有一个使用非常简单，但是非常强大的 bytes: + assert orjson is not None, "orjson must be installed" + return orjson.dumps(content, option=orjson.OPT_INDENT_2) + + +@app.get("/", response_class=CustomORJSONResponse) +async def main(): + return {"message": "Hello World"} diff --git a/docs_src/dataclasses/tutorial001.py b/docs_src/dataclasses/tutorial001.py index 43015eb27..2954c391f 100644 --- a/docs_src/dataclasses/tutorial001.py +++ b/docs_src/dataclasses/tutorial001.py @@ -1,5 +1,5 @@ from dataclasses import dataclass -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -8,8 +8,8 @@ from fastapi import FastAPI class Item: name: str price: float - description: Optional[str] = None - tax: Optional[float] = None + description: Union[str, None] = None + tax: Union[float, None] = None app = FastAPI() diff --git a/docs_src/dataclasses/tutorial002.py b/docs_src/dataclasses/tutorial002.py index aaa7b8799..08a238080 100644 --- a/docs_src/dataclasses/tutorial002.py +++ b/docs_src/dataclasses/tutorial002.py @@ -1,5 +1,5 @@ from dataclasses import dataclass, field -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI @@ -9,8 +9,8 @@ class Item: name: str price: float tags: List[str] = field(default_factory=list) - description: Optional[str] = None - tax: Optional[float] = None + description: Union[str, None] = None + tax: Union[float, None] = None app = FastAPI() diff --git a/docs_src/dataclasses/tutorial003.py b/docs_src/dataclasses/tutorial003.py index 2c1fccdd7..34ce1199e 100644 --- a/docs_src/dataclasses/tutorial003.py +++ b/docs_src/dataclasses/tutorial003.py @@ -1,5 +1,5 @@ from dataclasses import field # (1) -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI from pydantic.dataclasses import dataclass # (2) @@ -8,7 +8,7 @@ from pydantic.dataclasses import dataclass # (2) @dataclass class Item: name: str - description: Optional[str] = None + description: Union[str, None] = None @dataclass diff --git a/docs_src/dependencies/tutorial001.py b/docs_src/dependencies/tutorial001.py index a9da971dc..b1275103a 100644 --- a/docs_src/dependencies/tutorial001.py +++ b/docs_src/dependencies/tutorial001.py @@ -1,11 +1,13 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI app = FastAPI() -async def common_parameters(q: Optional[str] = None, skip: int = 0, limit: int = 100): +async def common_parameters( + q: Union[str, None] = None, skip: int = 0, limit: int = 100 +): return {"q": q, "skip": skip, "limit": limit} diff --git a/docs_src/dependencies/tutorial002.py b/docs_src/dependencies/tutorial002.py index 458f6b5bb..8e863e4fa 100644 --- a/docs_src/dependencies/tutorial002.py +++ b/docs_src/dependencies/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI @@ -9,7 +9,7 @@ fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz" class CommonQueryParams: - def __init__(self, q: Optional[str] = None, skip: int = 0, limit: int = 100): + def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100): self.q = q self.skip = skip self.limit = limit diff --git a/docs_src/dependencies/tutorial003.py b/docs_src/dependencies/tutorial003.py index 3f3e940f8..34614e539 100644 --- a/docs_src/dependencies/tutorial003.py +++ b/docs_src/dependencies/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI @@ -9,7 +9,7 @@ fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz" class CommonQueryParams: - def __init__(self, q: Optional[str] = None, skip: int = 0, limit: int = 100): + def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100): self.q = q self.skip = skip self.limit = limit diff --git a/docs_src/dependencies/tutorial004.py b/docs_src/dependencies/tutorial004.py index daa7b4670..d9fe88148 100644 --- a/docs_src/dependencies/tutorial004.py +++ b/docs_src/dependencies/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI @@ -9,7 +9,7 @@ fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz" class CommonQueryParams: - def __init__(self, q: Optional[str] = None, skip: int = 0, limit: int = 100): + def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100): self.q = q self.skip = skip self.limit = limit diff --git a/docs_src/dependencies/tutorial005.py b/docs_src/dependencies/tutorial005.py index c8923d143..697332b5b 100644 --- a/docs_src/dependencies/tutorial005.py +++ b/docs_src/dependencies/tutorial005.py @@ -1,16 +1,17 @@ -from typing import Optional +from typing import Union from fastapi import Cookie, Depends, FastAPI app = FastAPI() -def query_extractor(q: Optional[str] = None): +def query_extractor(q: Union[str, None] = None): return q def query_or_cookie_extractor( - q: str = Depends(query_extractor), last_query: Optional[str] = Cookie(None) + q: str = Depends(query_extractor), + last_query: Union[str, None] = Cookie(default=None), ): if not q: return last_query diff --git a/docs_src/dependencies/tutorial005_py310.py b/docs_src/dependencies/tutorial005_py310.py index 5e1d7e0ef..247cdabe2 100644 --- a/docs_src/dependencies/tutorial005_py310.py +++ b/docs_src/dependencies/tutorial005_py310.py @@ -8,7 +8,7 @@ def query_extractor(q: str | None = None): def query_or_cookie_extractor( - q: str = Depends(query_extractor), last_query: str | None = Cookie(None) + q: str = Depends(query_extractor), last_query: str | None = Cookie(default=None) ): if not q: return last_query diff --git a/docs_src/dependencies/tutorial006.py b/docs_src/dependencies/tutorial006.py index a71d7cce6..9aff4154f 100644 --- a/docs_src/dependencies/tutorial006.py +++ b/docs_src/dependencies/tutorial006.py @@ -3,12 +3,12 @@ from fastapi import Depends, FastAPI, Header, HTTPException app = FastAPI() -async def verify_token(x_token: str = Header(...)): +async def verify_token(x_token: str = Header()): if x_token != "fake-super-secret-token": raise HTTPException(status_code=400, detail="X-Token header invalid") -async def verify_key(x_key: str = Header(...)): +async def verify_key(x_key: str = Header()): if x_key != "fake-super-secret-key": raise HTTPException(status_code=400, detail="X-Key header invalid") return x_key diff --git a/docs_src/dependencies/tutorial012.py b/docs_src/dependencies/tutorial012.py index 8f8868a55..36ce6c711 100644 --- a/docs_src/dependencies/tutorial012.py +++ b/docs_src/dependencies/tutorial012.py @@ -1,12 +1,12 @@ from fastapi import Depends, FastAPI, Header, HTTPException -async def verify_token(x_token: str = Header(...)): +async def verify_token(x_token: str = Header()): if x_token != "fake-super-secret-token": raise HTTPException(status_code=400, detail="X-Token header invalid") -async def verify_key(x_key: str = Header(...)): +async def verify_key(x_key: str = Header()): if x_key != "fake-super-secret-key": raise HTTPException(status_code=400, detail="X-Key header invalid") return x_key diff --git a/docs_src/dependency_testing/tutorial001.py b/docs_src/dependency_testing/tutorial001.py index 237d3b231..a5fe1d9bf 100644 --- a/docs_src/dependency_testing/tutorial001.py +++ b/docs_src/dependency_testing/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI from fastapi.testclient import TestClient @@ -6,7 +6,9 @@ from fastapi.testclient import TestClient app = FastAPI() -async def common_parameters(q: Optional[str] = None, skip: int = 0, limit: int = 100): +async def common_parameters( + q: Union[str, None] = None, skip: int = 0, limit: int = 100 +): return {"q": q, "skip": skip, "limit": limit} @@ -23,7 +25,7 @@ async def read_users(commons: dict = Depends(common_parameters)): client = TestClient(app) -async def override_dependency(q: Optional[str] = None): +async def override_dependency(q: Union[str, None] = None): return {"q": q, "skip": 5, "limit": 10} diff --git a/docs_src/encoder/tutorial001.py b/docs_src/encoder/tutorial001.py index a918fdd64..5f7e7061e 100644 --- a/docs_src/encoder/tutorial001.py +++ b/docs_src/encoder/tutorial001.py @@ -1,5 +1,5 @@ from datetime import datetime -from typing import Optional +from typing import Union from fastapi import FastAPI from fastapi.encoders import jsonable_encoder @@ -11,7 +11,7 @@ fake_db = {} class Item(BaseModel): title: str timestamp: datetime - description: Optional[str] = None + description: Union[str, None] = None app = FastAPI() diff --git a/docs_src/extra_data_types/tutorial001.py b/docs_src/extra_data_types/tutorial001.py index e8d7e1ea3..8ae8472a7 100644 --- a/docs_src/extra_data_types/tutorial001.py +++ b/docs_src/extra_data_types/tutorial001.py @@ -1,5 +1,5 @@ from datetime import datetime, time, timedelta -from typing import Optional +from typing import Union from uuid import UUID from fastapi import Body, FastAPI @@ -10,10 +10,10 @@ app = FastAPI() @app.put("/items/{item_id}") async def read_items( item_id: UUID, - start_datetime: Optional[datetime] = Body(None), - end_datetime: Optional[datetime] = Body(None), - repeat_at: Optional[time] = Body(None), - process_after: Optional[timedelta] = Body(None), + start_datetime: Union[datetime, None] = Body(default=None), + end_datetime: Union[datetime, None] = Body(default=None), + repeat_at: Union[time, None] = Body(default=None), + process_after: Union[timedelta, None] = Body(default=None), ): start_process = start_datetime + process_after duration = end_datetime - start_process diff --git a/docs_src/extra_data_types/tutorial001_py310.py b/docs_src/extra_data_types/tutorial001_py310.py index 4a33481b7..d22f81888 100644 --- a/docs_src/extra_data_types/tutorial001_py310.py +++ b/docs_src/extra_data_types/tutorial001_py310.py @@ -9,10 +9,10 @@ app = FastAPI() @app.put("/items/{item_id}") async def read_items( item_id: UUID, - start_datetime: datetime | None = Body(None), - end_datetime: datetime | None = Body(None), - repeat_at: time | None = Body(None), - process_after: timedelta | None = Body(None), + start_datetime: datetime | None = Body(default=None), + end_datetime: datetime | None = Body(default=None), + repeat_at: time | None = Body(default=None), + process_after: timedelta | None = Body(default=None), ): start_process = start_datetime + process_after duration = end_datetime - start_process diff --git a/docs_src/extra_models/tutorial001.py b/docs_src/extra_models/tutorial001.py index e95844f60..4be56cd2a 100644 --- a/docs_src/extra_models/tutorial001.py +++ b/docs_src/extra_models/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel, EmailStr @@ -10,20 +10,20 @@ class UserIn(BaseModel): username: str password: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None class UserOut(BaseModel): username: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None class UserInDB(BaseModel): username: str hashed_password: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None def fake_password_hasher(raw_password: str): diff --git a/docs_src/extra_models/tutorial002.py b/docs_src/extra_models/tutorial002.py index 5bc6e707f..70fa16441 100644 --- a/docs_src/extra_models/tutorial002.py +++ b/docs_src/extra_models/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel, EmailStr @@ -9,7 +9,7 @@ app = FastAPI() class UserBase(BaseModel): username: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None class UserIn(UserBase): diff --git a/docs_src/generate_clients/tutorial001.py b/docs_src/generate_clients/tutorial001.py new file mode 100644 index 000000000..2d1f91bc6 --- /dev/null +++ b/docs_src/generate_clients/tutorial001.py @@ -0,0 +1,28 @@ +from typing import List + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +@app.post("/items/", response_model=ResponseMessage) +async def create_item(item: Item): + return {"message": "item received"} + + +@app.get("/items/", response_model=List[Item]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] diff --git a/docs_src/generate_clients/tutorial001_py39.py b/docs_src/generate_clients/tutorial001_py39.py new file mode 100644 index 000000000..6a5ae2320 --- /dev/null +++ b/docs_src/generate_clients/tutorial001_py39.py @@ -0,0 +1,26 @@ +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +@app.post("/items/", response_model=ResponseMessage) +async def create_item(item: Item): + return {"message": "item received"} + + +@app.get("/items/", response_model=list[Item]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] diff --git a/docs_src/generate_clients/tutorial002.py b/docs_src/generate_clients/tutorial002.py new file mode 100644 index 000000000..bd80449af --- /dev/null +++ b/docs_src/generate_clients/tutorial002.py @@ -0,0 +1,38 @@ +from typing import List + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +class User(BaseModel): + username: str + email: str + + +@app.post("/items/", response_model=ResponseMessage, tags=["items"]) +async def create_item(item: Item): + return {"message": "Item received"} + + +@app.get("/items/", response_model=List[Item], tags=["items"]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] + + +@app.post("/users/", response_model=ResponseMessage, tags=["users"]) +async def create_user(user: User): + return {"message": "User received"} diff --git a/docs_src/generate_clients/tutorial002_py39.py b/docs_src/generate_clients/tutorial002_py39.py new file mode 100644 index 000000000..83309760b --- /dev/null +++ b/docs_src/generate_clients/tutorial002_py39.py @@ -0,0 +1,36 @@ +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +class User(BaseModel): + username: str + email: str + + +@app.post("/items/", response_model=ResponseMessage, tags=["items"]) +async def create_item(item: Item): + return {"message": "Item received"} + + +@app.get("/items/", response_model=list[Item], tags=["items"]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] + + +@app.post("/users/", response_model=ResponseMessage, tags=["users"]) +async def create_user(user: User): + return {"message": "User received"} diff --git a/docs_src/generate_clients/tutorial003.py b/docs_src/generate_clients/tutorial003.py new file mode 100644 index 000000000..49eab73a1 --- /dev/null +++ b/docs_src/generate_clients/tutorial003.py @@ -0,0 +1,44 @@ +from typing import List + +from fastapi import FastAPI +from fastapi.routing import APIRoute +from pydantic import BaseModel + + +def custom_generate_unique_id(route: APIRoute): + return f"{route.tags[0]}-{route.name}" + + +app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +class User(BaseModel): + username: str + email: str + + +@app.post("/items/", response_model=ResponseMessage, tags=["items"]) +async def create_item(item: Item): + return {"message": "Item received"} + + +@app.get("/items/", response_model=List[Item], tags=["items"]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] + + +@app.post("/users/", response_model=ResponseMessage, tags=["users"]) +async def create_user(user: User): + return {"message": "User received"} diff --git a/docs_src/generate_clients/tutorial003_py39.py b/docs_src/generate_clients/tutorial003_py39.py new file mode 100644 index 000000000..40722cf10 --- /dev/null +++ b/docs_src/generate_clients/tutorial003_py39.py @@ -0,0 +1,42 @@ +from fastapi import FastAPI +from fastapi.routing import APIRoute +from pydantic import BaseModel + + +def custom_generate_unique_id(route: APIRoute): + return f"{route.tags[0]}-{route.name}" + + +app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + + +class Item(BaseModel): + name: str + price: float + + +class ResponseMessage(BaseModel): + message: str + + +class User(BaseModel): + username: str + email: str + + +@app.post("/items/", response_model=ResponseMessage, tags=["items"]) +async def create_item(item: Item): + return {"message": "Item received"} + + +@app.get("/items/", response_model=list[Item], tags=["items"]) +async def get_items(): + return [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] + + +@app.post("/users/", response_model=ResponseMessage, tags=["users"]) +async def create_user(user: User): + return {"message": "User received"} diff --git a/docs_src/generate_clients/tutorial004.py b/docs_src/generate_clients/tutorial004.py new file mode 100644 index 000000000..894dc7f8d --- /dev/null +++ b/docs_src/generate_clients/tutorial004.py @@ -0,0 +1,15 @@ +import json +from pathlib import Path + +file_path = Path("./openapi.json") +openapi_content = json.loads(file_path.read_text()) + +for path_data in openapi_content["paths"].values(): + for operation in path_data.values(): + tag = operation["tags"][0] + operation_id = operation["operationId"] + to_remove = f"{tag}-" + new_operation_id = operation_id[len(to_remove) :] + operation["operationId"] = new_operation_id + +file_path.write_text(json.dumps(openapi_content)) diff --git a/docs_src/header_params/tutorial001.py b/docs_src/header_params/tutorial001.py index 7d69b027e..74429c8e2 100644 --- a/docs_src/header_params/tutorial001.py +++ b/docs_src/header_params/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Header @@ -6,5 +6,5 @@ app = FastAPI() @app.get("/items/") -async def read_items(user_agent: Optional[str] = Header(None)): +async def read_items(user_agent: Union[str, None] = Header(default=None)): return {"User-Agent": user_agent} diff --git a/docs_src/header_params/tutorial001_py310.py b/docs_src/header_params/tutorial001_py310.py index b28463346..2203ed1b8 100644 --- a/docs_src/header_params/tutorial001_py310.py +++ b/docs_src/header_params/tutorial001_py310.py @@ -4,5 +4,5 @@ app = FastAPI() @app.get("/items/") -async def read_items(user_agent: str | None = Header(None)): +async def read_items(user_agent: str | None = Header(default=None)): return {"User-Agent": user_agent} diff --git a/docs_src/header_params/tutorial002.py b/docs_src/header_params/tutorial002.py index 2de3dddd7..639ab1735 100644 --- a/docs_src/header_params/tutorial002.py +++ b/docs_src/header_params/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Header @@ -7,6 +7,6 @@ app = FastAPI() @app.get("/items/") async def read_items( - strange_header: Optional[str] = Header(None, convert_underscores=False) + strange_header: Union[str, None] = Header(default=None, convert_underscores=False) ): return {"strange_header": strange_header} diff --git a/docs_src/header_params/tutorial002_py310.py b/docs_src/header_params/tutorial002_py310.py index 98ab5a807..b7979b542 100644 --- a/docs_src/header_params/tutorial002_py310.py +++ b/docs_src/header_params/tutorial002_py310.py @@ -5,6 +5,6 @@ app = FastAPI() @app.get("/items/") async def read_items( - strange_header: str | None = Header(None, convert_underscores=False) + strange_header: str | None = Header(default=None, convert_underscores=False) ): return {"strange_header": strange_header} diff --git a/docs_src/header_params/tutorial003.py b/docs_src/header_params/tutorial003.py index 6d0eefdd2..a61314aed 100644 --- a/docs_src/header_params/tutorial003.py +++ b/docs_src/header_params/tutorial003.py @@ -1,4 +1,4 @@ -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI, Header @@ -6,5 +6,5 @@ app = FastAPI() @app.get("/items/") -async def read_items(x_token: Optional[List[str]] = Header(None)): +async def read_items(x_token: Union[List[str], None] = Header(default=None)): return {"X-Token values": x_token} diff --git a/docs_src/header_params/tutorial003_py310.py b/docs_src/header_params/tutorial003_py310.py index 2dac2c13c..435c67574 100644 --- a/docs_src/header_params/tutorial003_py310.py +++ b/docs_src/header_params/tutorial003_py310.py @@ -4,5 +4,5 @@ app = FastAPI() @app.get("/items/") -async def read_items(x_token: list[str] | None = Header(None)): +async def read_items(x_token: list[str] | None = Header(default=None)): return {"X-Token values": x_token} diff --git a/docs_src/header_params/tutorial003_py39.py b/docs_src/header_params/tutorial003_py39.py index 359766527..34437db16 100644 --- a/docs_src/header_params/tutorial003_py39.py +++ b/docs_src/header_params/tutorial003_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Header @@ -6,5 +6,5 @@ app = FastAPI() @app.get("/items/") -async def read_items(x_token: Optional[list[str]] = Header(None)): +async def read_items(x_token: Union[list[str], None] = Header(default=None)): return {"X-Token values": x_token} diff --git a/docs_src/nosql_databases/tutorial001.py b/docs_src/nosql_databases/tutorial001.py index 39548d862..91893e528 100644 --- a/docs_src/nosql_databases/tutorial001.py +++ b/docs_src/nosql_databases/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from couchbase import LOCKMODE_WAIT from couchbase.bucket import Bucket @@ -23,9 +23,9 @@ def get_bucket(): class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None class UserInDB(User): diff --git a/docs_src/openapi_callbacks/tutorial001.py b/docs_src/openapi_callbacks/tutorial001.py index 2fb836751..3f1bac6e2 100644 --- a/docs_src/openapi_callbacks/tutorial001.py +++ b/docs_src/openapi_callbacks/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import APIRouter, FastAPI from pydantic import BaseModel, HttpUrl @@ -8,7 +8,7 @@ app = FastAPI() class Invoice(BaseModel): id: str - title: Optional[str] = None + title: Union[str, None] = None customer: str total: float @@ -33,7 +33,7 @@ def invoice_notification(body: InvoiceEvent): @app.post("/invoices/", callbacks=invoices_callback_router.routes) -def create_invoice(invoice: Invoice, callback_url: Optional[HttpUrl] = None): +def create_invoice(invoice: Invoice, callback_url: Union[HttpUrl, None] = None): """ Create an invoice. diff --git a/docs_src/path_operation_advanced_configuration/tutorial004.py b/docs_src/path_operation_advanced_configuration/tutorial004.py index fa867e794..a3aad4ac4 100644 --- a/docs_src/path_operation_advanced_configuration/tutorial004.py +++ b/docs_src/path_operation_advanced_configuration/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,10 +8,10 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None - tags: Set[str] = [] + tax: Union[float, None] = None + tags: Set[str] = set() @app.post("/items/", response_model=Item, summary="Create an item") diff --git a/docs_src/path_operation_configuration/tutorial001.py b/docs_src/path_operation_configuration/tutorial001.py index 1316d9237..83fd8377a 100644 --- a/docs_src/path_operation_configuration/tutorial001.py +++ b/docs_src/path_operation_configuration/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI, status from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: Set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial001_py39.py b/docs_src/path_operation_configuration/tutorial001_py39.py index 5c04d8bac..a9dcbf389 100644 --- a/docs_src/path_operation_configuration/tutorial001_py39.py +++ b/docs_src/path_operation_configuration/tutorial001_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, status from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial002.py b/docs_src/path_operation_configuration/tutorial002.py index 2df537d86..798b0c231 100644 --- a/docs_src/path_operation_configuration/tutorial002.py +++ b/docs_src/path_operation_configuration/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: Set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial002_py39.py b/docs_src/path_operation_configuration/tutorial002_py39.py index 766d9fb0b..e7ced7de7 100644 --- a/docs_src/path_operation_configuration/tutorial002_py39.py +++ b/docs_src/path_operation_configuration/tutorial002_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial003.py b/docs_src/path_operation_configuration/tutorial003.py index 269a1a253..26bf7daba 100644 --- a/docs_src/path_operation_configuration/tutorial003.py +++ b/docs_src/path_operation_configuration/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: Set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial003_py39.py b/docs_src/path_operation_configuration/tutorial003_py39.py index 446198b5c..607c5707e 100644 --- a/docs_src/path_operation_configuration/tutorial003_py39.py +++ b/docs_src/path_operation_configuration/tutorial003_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial004.py b/docs_src/path_operation_configuration/tutorial004.py index de83be836..8f865c58a 100644 --- a/docs_src/path_operation_configuration/tutorial004.py +++ b/docs_src/path_operation_configuration/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: Set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial004_py39.py b/docs_src/path_operation_configuration/tutorial004_py39.py index bf6005b95..fc25680c5 100644 --- a/docs_src/path_operation_configuration/tutorial004_py39.py +++ b/docs_src/path_operation_configuration/tutorial004_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial005.py b/docs_src/path_operation_configuration/tutorial005.py index 0f62c3814..2c1be4a34 100644 --- a/docs_src/path_operation_configuration/tutorial005.py +++ b/docs_src/path_operation_configuration/tutorial005.py @@ -1,4 +1,4 @@ -from typing import Optional, Set +from typing import Set, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: Set[str] = set() diff --git a/docs_src/path_operation_configuration/tutorial005_py39.py b/docs_src/path_operation_configuration/tutorial005_py39.py index 5ef320405..ddf29b733 100644 --- a/docs_src/path_operation_configuration/tutorial005_py39.py +++ b/docs_src/path_operation_configuration/tutorial005_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: set[str] = set() diff --git a/docs_src/path_params/tutorial003b.py b/docs_src/path_params/tutorial003b.py new file mode 100644 index 000000000..822d37369 --- /dev/null +++ b/docs_src/path_params/tutorial003b.py @@ -0,0 +1,13 @@ +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/users") +async def read_users(): + return ["Rick", "Morty"] + + +@app.get("/users") +async def read_users2(): + return ["Bean", "Elfo"] diff --git a/docs_src/path_params/tutorial005.py b/docs_src/path_params/tutorial005.py index 8e3767744..9a24a4963 100644 --- a/docs_src/path_params/tutorial005.py +++ b/docs_src/path_params/tutorial005.py @@ -14,7 +14,7 @@ app = FastAPI() @app.get("/models/{model_name}") async def get_model(model_name: ModelName): - if model_name == ModelName.alexnet: + if model_name is ModelName.alexnet: return {"model_name": model_name, "message": "Deep Learning FTW!"} if model_name.value == "lenet": diff --git a/docs_src/path_params_numeric_validations/tutorial001.py b/docs_src/path_params_numeric_validations/tutorial001.py index 11777bba7..530147028 100644 --- a/docs_src/path_params_numeric_validations/tutorial001.py +++ b/docs_src/path_params_numeric_validations/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Path, Query @@ -7,8 +7,8 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_items( - item_id: int = Path(..., title="The ID of the item to get"), - q: Optional[str] = Query(None, alias="item-query"), + item_id: int = Path(title="The ID of the item to get"), + q: Union[str, None] = Query(default=None, alias="item-query"), ): results = {"item_id": item_id} if q: diff --git a/docs_src/path_params_numeric_validations/tutorial001_py310.py b/docs_src/path_params_numeric_validations/tutorial001_py310.py index b940a0949..b1a77cc9d 100644 --- a/docs_src/path_params_numeric_validations/tutorial001_py310.py +++ b/docs_src/path_params_numeric_validations/tutorial001_py310.py @@ -5,8 +5,8 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_items( - item_id: int = Path(..., title="The ID of the item to get"), - q: str | None = Query(None, alias="item-query"), + item_id: int = Path(title="The ID of the item to get"), + q: str | None = Query(default=None, alias="item-query"), ): results = {"item_id": item_id} if q: diff --git a/docs_src/path_params_numeric_validations/tutorial002.py b/docs_src/path_params_numeric_validations/tutorial002.py index 57ca50ece..63ac691a8 100644 --- a/docs_src/path_params_numeric_validations/tutorial002.py +++ b/docs_src/path_params_numeric_validations/tutorial002.py @@ -4,9 +4,7 @@ app = FastAPI() @app.get("/items/{item_id}") -async def read_items( - q: str, item_id: int = Path(..., title="The ID of the item to get") -): +async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")): results = {"item_id": item_id} if q: results.update({"q": q}) diff --git a/docs_src/path_params_numeric_validations/tutorial003.py b/docs_src/path_params_numeric_validations/tutorial003.py index b6b5a1986..8df0ffc62 100644 --- a/docs_src/path_params_numeric_validations/tutorial003.py +++ b/docs_src/path_params_numeric_validations/tutorial003.py @@ -4,9 +4,7 @@ app = FastAPI() @app.get("/items/{item_id}") -async def read_items( - *, item_id: int = Path(..., title="The ID of the item to get"), q: str -): +async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str): results = {"item_id": item_id} if q: results.update({"q": q}) diff --git a/docs_src/path_params_numeric_validations/tutorial004.py b/docs_src/path_params_numeric_validations/tutorial004.py index 2ec708280..86651d47c 100644 --- a/docs_src/path_params_numeric_validations/tutorial004.py +++ b/docs_src/path_params_numeric_validations/tutorial004.py @@ -5,7 +5,7 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_items( - *, item_id: int = Path(..., title="The ID of the item to get", ge=1), q: str + *, item_id: int = Path(title="The ID of the item to get", ge=1), q: str ): results = {"item_id": item_id} if q: diff --git a/docs_src/path_params_numeric_validations/tutorial005.py b/docs_src/path_params_numeric_validations/tutorial005.py index 2809f37b2..8f12f2da0 100644 --- a/docs_src/path_params_numeric_validations/tutorial005.py +++ b/docs_src/path_params_numeric_validations/tutorial005.py @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_items( *, - item_id: int = Path(..., title="The ID of the item to get", gt=0, le=1000), + item_id: int = Path(title="The ID of the item to get", gt=0, le=1000), q: str, ): results = {"item_id": item_id} diff --git a/docs_src/path_params_numeric_validations/tutorial006.py b/docs_src/path_params_numeric_validations/tutorial006.py index 0c19579f5..85bd6e8b4 100644 --- a/docs_src/path_params_numeric_validations/tutorial006.py +++ b/docs_src/path_params_numeric_validations/tutorial006.py @@ -6,9 +6,9 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_items( *, - item_id: int = Path(..., title="The ID of the item to get", ge=0, le=1000), + item_id: int = Path(title="The ID of the item to get", ge=0, le=1000), q: str, - size: float = Query(..., gt=0, lt=10.5) + size: float = Query(gt=0, lt=10.5) ): results = {"item_id": item_id} if q: diff --git a/docs_src/python_types/tutorial009c.py b/docs_src/python_types/tutorial009c.py new file mode 100644 index 000000000..2f539a34b --- /dev/null +++ b/docs_src/python_types/tutorial009c.py @@ -0,0 +1,5 @@ +from typing import Optional + + +def say_hi(name: Optional[str]): + print(f"Hey {name}!") diff --git a/docs_src/python_types/tutorial009c_py310.py b/docs_src/python_types/tutorial009c_py310.py new file mode 100644 index 000000000..96b1220fc --- /dev/null +++ b/docs_src/python_types/tutorial009c_py310.py @@ -0,0 +1,2 @@ +def say_hi(name: str | None): + print(f"Hey {name}!") diff --git a/docs_src/python_types/tutorial011.py b/docs_src/python_types/tutorial011.py index 047b633b5..c8634cbff 100644 --- a/docs_src/python_types/tutorial011.py +++ b/docs_src/python_types/tutorial011.py @@ -1,5 +1,5 @@ from datetime import datetime -from typing import List, Optional +from typing import List, Union from pydantic import BaseModel @@ -7,7 +7,7 @@ from pydantic import BaseModel class User(BaseModel): id: int name = "John Doe" - signup_ts: Optional[datetime] = None + signup_ts: Union[datetime, None] = None friends: List[int] = [] diff --git a/docs_src/python_types/tutorial011_py39.py b/docs_src/python_types/tutorial011_py39.py index af79e2df0..468496f51 100644 --- a/docs_src/python_types/tutorial011_py39.py +++ b/docs_src/python_types/tutorial011_py39.py @@ -1,5 +1,5 @@ from datetime import datetime -from typing import Optional +from typing import Union from pydantic import BaseModel @@ -7,7 +7,7 @@ from pydantic import BaseModel class User(BaseModel): id: int name = "John Doe" - signup_ts: Optional[datetime] = None + signup_ts: Union[datetime, None] = None friends: list[int] = [] diff --git a/docs_src/python_types/tutorial012.py b/docs_src/python_types/tutorial012.py new file mode 100644 index 000000000..74fa94c43 --- /dev/null +++ b/docs_src/python_types/tutorial012.py @@ -0,0 +1,8 @@ +from typing import Optional + +from pydantic import BaseModel + + +class User(BaseModel): + name: str + age: Optional[int] diff --git a/docs_src/query_params/tutorial002.py b/docs_src/query_params/tutorial002.py index 32918465e..8465f45ee 100644 --- a/docs_src/query_params/tutorial002.py +++ b/docs_src/query_params/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/{item_id}") -async def read_item(item_id: str, q: Optional[str] = None): +async def read_item(item_id: str, q: Union[str, None] = None): if q: return {"item_id": item_id, "q": q} return {"item_id": item_id} diff --git a/docs_src/query_params/tutorial003.py b/docs_src/query_params/tutorial003.py index c81a96785..3362715b3 100644 --- a/docs_src/query_params/tutorial003.py +++ b/docs_src/query_params/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/{item_id}") -async def read_item(item_id: str, q: Optional[str] = None, short: bool = False): +async def read_item(item_id: str, q: Union[str, None] = None, short: bool = False): item = {"item_id": item_id} if q: item.update({"q": q}) diff --git a/docs_src/query_params/tutorial004.py b/docs_src/query_params/tutorial004.py index 37f97fa2a..049c3ae93 100644 --- a/docs_src/query_params/tutorial004.py +++ b/docs_src/query_params/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -7,7 +7,7 @@ app = FastAPI() @app.get("/users/{user_id}/items/{item_id}") async def read_user_item( - user_id: int, item_id: str, q: Optional[str] = None, short: bool = False + user_id: int, item_id: str, q: Union[str, None] = None, short: bool = False ): item = {"item_id": item_id, "owner_id": user_id} if q: diff --git a/docs_src/query_params/tutorial006.py b/docs_src/query_params/tutorial006.py index ffe328340..f0dbfe08f 100644 --- a/docs_src/query_params/tutorial006.py +++ b/docs_src/query_params/tutorial006.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -7,7 +7,7 @@ app = FastAPI() @app.get("/items/{item_id}") async def read_user_item( - item_id: str, needy: str, skip: int = 0, limit: Optional[int] = None + item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None ): item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit} return item diff --git a/docs_src/query_params_str_validations/tutorial001.py b/docs_src/query_params_str_validations/tutorial001.py index 5d7bfb0ee..e38326b18 100644 --- a/docs_src/query_params_str_validations/tutorial001.py +++ b/docs_src/query_params_str_validations/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[str] = None): +async def read_items(q: Union[str, None] = None): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial002.py b/docs_src/query_params_str_validations/tutorial002.py index 68ea58206..17e017b7e 100644 --- a/docs_src/query_params_str_validations/tutorial002.py +++ b/docs_src/query_params_str_validations/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[str] = Query(None, max_length=50)): +async def read_items(q: Union[str, None] = Query(default=None, max_length=50)): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial002_py310.py b/docs_src/query_params_str_validations/tutorial002_py310.py index fa3139d5a..f15351d29 100644 --- a/docs_src/query_params_str_validations/tutorial002_py310.py +++ b/docs_src/query_params_str_validations/tutorial002_py310.py @@ -4,7 +4,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str | None = Query(None, max_length=50)): +async def read_items(q: str | None = Query(default=None, max_length=50)): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial003.py b/docs_src/query_params_str_validations/tutorial003.py index e52acc72f..73d2e08c8 100644 --- a/docs_src/query_params_str_validations/tutorial003.py +++ b/docs_src/query_params_str_validations/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -6,7 +6,9 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[str] = Query(None, min_length=3, max_length=50)): +async def read_items( + q: Union[str, None] = Query(default=None, min_length=3, max_length=50) +): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial003_py310.py b/docs_src/query_params_str_validations/tutorial003_py310.py index 335858a40..dc60ecb39 100644 --- a/docs_src/query_params_str_validations/tutorial003_py310.py +++ b/docs_src/query_params_str_validations/tutorial003_py310.py @@ -4,7 +4,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str | None = Query(None, min_length=3, max_length=50)): +async def read_items(q: str | None = Query(default=None, min_length=3, max_length=50)): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial004.py b/docs_src/query_params_str_validations/tutorial004.py index d2c30331f..5a7129816 100644 --- a/docs_src/query_params_str_validations/tutorial004.py +++ b/docs_src/query_params_str_validations/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -7,7 +7,9 @@ app = FastAPI() @app.get("/items/") async def read_items( - q: Optional[str] = Query(None, min_length=3, max_length=50, regex="^fixedquery$") + q: Union[str, None] = Query( + default=None, min_length=3, max_length=50, regex="^fixedquery$" + ) ): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: diff --git a/docs_src/query_params_str_validations/tutorial004_py310.py b/docs_src/query_params_str_validations/tutorial004_py310.py index 518b779f7..180a2e511 100644 --- a/docs_src/query_params_str_validations/tutorial004_py310.py +++ b/docs_src/query_params_str_validations/tutorial004_py310.py @@ -5,7 +5,8 @@ app = FastAPI() @app.get("/items/") async def read_items( - q: str | None = Query(None, min_length=3, max_length=50, regex="^fixedquery$") + q: str + | None = Query(default=None, min_length=3, max_length=50, regex="^fixedquery$") ): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: diff --git a/docs_src/query_params_str_validations/tutorial005.py b/docs_src/query_params_str_validations/tutorial005.py index 22eb3acba..8ab42869e 100644 --- a/docs_src/query_params_str_validations/tutorial005.py +++ b/docs_src/query_params_str_validations/tutorial005.py @@ -4,7 +4,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str = Query("fixedquery", min_length=3)): +async def read_items(q: str = Query(default="fixedquery", min_length=3)): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial006.py b/docs_src/query_params_str_validations/tutorial006.py index 720bf07f1..9a90eb64e 100644 --- a/docs_src/query_params_str_validations/tutorial006.py +++ b/docs_src/query_params_str_validations/tutorial006.py @@ -4,7 +4,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str = Query(..., min_length=3)): +async def read_items(q: str = Query(min_length=3)): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial006b.py b/docs_src/query_params_str_validations/tutorial006b.py new file mode 100644 index 000000000..a8d69c889 --- /dev/null +++ b/docs_src/query_params_str_validations/tutorial006b.py @@ -0,0 +1,11 @@ +from fastapi import FastAPI, Query + +app = FastAPI() + + +@app.get("/items/") +async def read_items(q: str = Query(default=..., min_length=3)): + results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} + if q: + results.update({"q": q}) + return results diff --git a/docs_src/query_params_str_validations/tutorial006c.py b/docs_src/query_params_str_validations/tutorial006c.py new file mode 100644 index 000000000..2ac148c94 --- /dev/null +++ b/docs_src/query_params_str_validations/tutorial006c.py @@ -0,0 +1,13 @@ +from typing import Union + +from fastapi import FastAPI, Query + +app = FastAPI() + + +@app.get("/items/") +async def read_items(q: Union[str, None] = Query(default=..., min_length=3)): + results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} + if q: + results.update({"q": q}) + return results diff --git a/docs_src/query_params_str_validations/tutorial006c_py310.py b/docs_src/query_params_str_validations/tutorial006c_py310.py new file mode 100644 index 000000000..82dd9e5d7 --- /dev/null +++ b/docs_src/query_params_str_validations/tutorial006c_py310.py @@ -0,0 +1,11 @@ +from fastapi import FastAPI, Query + +app = FastAPI() + + +@app.get("/items/") +async def read_items(q: str | None = Query(default=..., min_length=3)): + results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} + if q: + results.update({"q": q}) + return results diff --git a/docs_src/query_params_str_validations/tutorial006d.py b/docs_src/query_params_str_validations/tutorial006d.py new file mode 100644 index 000000000..42c5bf4eb --- /dev/null +++ b/docs_src/query_params_str_validations/tutorial006d.py @@ -0,0 +1,12 @@ +from fastapi import FastAPI, Query +from pydantic import Required + +app = FastAPI() + + +@app.get("/items/") +async def read_items(q: str = Query(default=Required, min_length=3)): + results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} + if q: + results.update({"q": q}) + return results diff --git a/docs_src/query_params_str_validations/tutorial007.py b/docs_src/query_params_str_validations/tutorial007.py index e360feda9..cb836569e 100644 --- a/docs_src/query_params_str_validations/tutorial007.py +++ b/docs_src/query_params_str_validations/tutorial007.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -7,7 +7,7 @@ app = FastAPI() @app.get("/items/") async def read_items( - q: Optional[str] = Query(None, title="Query string", min_length=3) + q: Union[str, None] = Query(default=None, title="Query string", min_length=3) ): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: diff --git a/docs_src/query_params_str_validations/tutorial007_py310.py b/docs_src/query_params_str_validations/tutorial007_py310.py index 14ef4cb69..e3e1ef2e0 100644 --- a/docs_src/query_params_str_validations/tutorial007_py310.py +++ b/docs_src/query_params_str_validations/tutorial007_py310.py @@ -4,7 +4,9 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str | None = Query(None, title="Query string", min_length=3)): +async def read_items( + q: str | None = Query(default=None, title="Query string", min_length=3) +): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial008.py b/docs_src/query_params_str_validations/tutorial008.py index 238add471..d112a9ab8 100644 --- a/docs_src/query_params_str_validations/tutorial008.py +++ b/docs_src/query_params_str_validations/tutorial008.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -7,8 +7,8 @@ app = FastAPI() @app.get("/items/") async def read_items( - q: Optional[str] = Query( - None, + q: Union[str, None] = Query( + default=None, title="Query string", description="Query string for the items to search in the database that have a good match", min_length=3, diff --git a/docs_src/query_params_str_validations/tutorial008_py310.py b/docs_src/query_params_str_validations/tutorial008_py310.py index 06bb02442..489f631d5 100644 --- a/docs_src/query_params_str_validations/tutorial008_py310.py +++ b/docs_src/query_params_str_validations/tutorial008_py310.py @@ -7,7 +7,7 @@ app = FastAPI() async def read_items( q: str | None = Query( - None, + default=None, title="Query string", description="Query string for the items to search in the database that have a good match", min_length=3, diff --git a/docs_src/query_params_str_validations/tutorial009.py b/docs_src/query_params_str_validations/tutorial009.py index 7e5c0b81a..8a6bfe2d9 100644 --- a/docs_src/query_params_str_validations/tutorial009.py +++ b/docs_src/query_params_str_validations/tutorial009.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[str] = Query(None, alias="item-query")): +async def read_items(q: Union[str, None] = Query(default=None, alias="item-query")): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial009_py310.py b/docs_src/query_params_str_validations/tutorial009_py310.py index e84c116f1..a38d32cbb 100644 --- a/docs_src/query_params_str_validations/tutorial009_py310.py +++ b/docs_src/query_params_str_validations/tutorial009_py310.py @@ -4,7 +4,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: str | None = Query(None, alias="item-query")): +async def read_items(q: str | None = Query(default=None, alias="item-query")): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q}) diff --git a/docs_src/query_params_str_validations/tutorial010.py b/docs_src/query_params_str_validations/tutorial010.py index 7921506b6..35443d194 100644 --- a/docs_src/query_params_str_validations/tutorial010.py +++ b/docs_src/query_params_str_validations/tutorial010.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -7,8 +7,8 @@ app = FastAPI() @app.get("/items/") async def read_items( - q: Optional[str] = Query( - None, + q: Union[str, None] = Query( + default=None, alias="item-query", title="Query string", description="Query string for the items to search in the database that have a good match", diff --git a/docs_src/query_params_str_validations/tutorial010_py310.py b/docs_src/query_params_str_validations/tutorial010_py310.py index c35800858..f2839516e 100644 --- a/docs_src/query_params_str_validations/tutorial010_py310.py +++ b/docs_src/query_params_str_validations/tutorial010_py310.py @@ -7,7 +7,7 @@ app = FastAPI() async def read_items( q: str | None = Query( - None, + default=None, alias="item-query", title="Query string", description="Query string for the items to search in the database that have a good match", diff --git a/docs_src/query_params_str_validations/tutorial011.py b/docs_src/query_params_str_validations/tutorial011.py index 7fda267ed..65bbce781 100644 --- a/docs_src/query_params_str_validations/tutorial011.py +++ b/docs_src/query_params_str_validations/tutorial011.py @@ -1,4 +1,4 @@ -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI, Query @@ -6,6 +6,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[List[str]] = Query(None)): +async def read_items(q: Union[List[str], None] = Query(default=None)): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial011_py310.py b/docs_src/query_params_str_validations/tutorial011_py310.py index c3d992e62..70155de7c 100644 --- a/docs_src/query_params_str_validations/tutorial011_py310.py +++ b/docs_src/query_params_str_validations/tutorial011_py310.py @@ -4,6 +4,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: list[str] | None = Query(None)): +async def read_items(q: list[str] | None = Query(default=None)): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial011_py39.py b/docs_src/query_params_str_validations/tutorial011_py39.py index 38ba764d6..878f95c79 100644 --- a/docs_src/query_params_str_validations/tutorial011_py39.py +++ b/docs_src/query_params_str_validations/tutorial011_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -6,6 +6,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Optional[list[str]] = Query(None)): +async def read_items(q: Union[list[str], None] = Query(default=None)): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial012.py b/docs_src/query_params_str_validations/tutorial012.py index 7ea9f017d..e77d56974 100644 --- a/docs_src/query_params_str_validations/tutorial012.py +++ b/docs_src/query_params_str_validations/tutorial012.py @@ -6,6 +6,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: List[str] = Query(["foo", "bar"])): +async def read_items(q: List[str] = Query(default=["foo", "bar"])): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial012_py39.py b/docs_src/query_params_str_validations/tutorial012_py39.py index 1900133d9..070d0b04b 100644 --- a/docs_src/query_params_str_validations/tutorial012_py39.py +++ b/docs_src/query_params_str_validations/tutorial012_py39.py @@ -4,6 +4,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: list[str] = Query(["foo", "bar"])): +async def read_items(q: list[str] = Query(default=["foo", "bar"])): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial013.py b/docs_src/query_params_str_validations/tutorial013.py index 95dd6999d..0b0f44869 100644 --- a/docs_src/query_params_str_validations/tutorial013.py +++ b/docs_src/query_params_str_validations/tutorial013.py @@ -4,6 +4,6 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: list = Query([])): +async def read_items(q: list = Query(default=[])): query_items = {"q": q} return query_items diff --git a/docs_src/query_params_str_validations/tutorial014.py b/docs_src/query_params_str_validations/tutorial014.py index fb50bc27b..50e0a6c2b 100644 --- a/docs_src/query_params_str_validations/tutorial014.py +++ b/docs_src/query_params_str_validations/tutorial014.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, Query @@ -7,7 +7,7 @@ app = FastAPI() @app.get("/items/") async def read_items( - hidden_query: Optional[str] = Query(None, include_in_schema=False) + hidden_query: Union[str, None] = Query(default=None, include_in_schema=False) ): if hidden_query: return {"hidden_query": hidden_query} diff --git a/docs_src/query_params_str_validations/tutorial014_py310.py b/docs_src/query_params_str_validations/tutorial014_py310.py index 7ae39c7f9..1b617efdd 100644 --- a/docs_src/query_params_str_validations/tutorial014_py310.py +++ b/docs_src/query_params_str_validations/tutorial014_py310.py @@ -4,7 +4,9 @@ app = FastAPI() @app.get("/items/") -async def read_items(hidden_query: str | None = Query(None, include_in_schema=False)): +async def read_items( + hidden_query: str | None = Query(default=None, include_in_schema=False) +): if hidden_query: return {"hidden_query": hidden_query} else: diff --git a/docs_src/request_files/tutorial001.py b/docs_src/request_files/tutorial001.py index 0fb1dd571..2e0ea6391 100644 --- a/docs_src/request_files/tutorial001.py +++ b/docs_src/request_files/tutorial001.py @@ -4,7 +4,7 @@ app = FastAPI() @app.post("/files/") -async def create_file(file: bytes = File(...)): +async def create_file(file: bytes = File()): return {"file_size": len(file)} diff --git a/docs_src/request_files/tutorial001_02.py b/docs_src/request_files/tutorial001_02.py index 26a4c9cbf..ac30be2d3 100644 --- a/docs_src/request_files/tutorial001_02.py +++ b/docs_src/request_files/tutorial001_02.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI, File, UploadFile @@ -6,7 +6,7 @@ app = FastAPI() @app.post("/files/") -async def create_file(file: Optional[bytes] = File(None)): +async def create_file(file: Union[bytes, None] = File(default=None)): if not file: return {"message": "No file sent"} else: @@ -14,7 +14,7 @@ async def create_file(file: Optional[bytes] = File(None)): @app.post("/uploadfile/") -async def create_upload_file(file: Optional[UploadFile] = None): +async def create_upload_file(file: Union[UploadFile, None] = None): if not file: return {"message": "No upload file sent"} else: diff --git a/docs_src/request_files/tutorial001_02_py310.py b/docs_src/request_files/tutorial001_02_py310.py index 0e576251b..298c9974f 100644 --- a/docs_src/request_files/tutorial001_02_py310.py +++ b/docs_src/request_files/tutorial001_02_py310.py @@ -4,7 +4,7 @@ app = FastAPI() @app.post("/files/") -async def create_file(file: bytes | None = File(None)): +async def create_file(file: bytes | None = File(default=None)): if not file: return {"message": "No file sent"} else: diff --git a/docs_src/request_files/tutorial001_03.py b/docs_src/request_files/tutorial001_03.py index abcac9e4c..d8005cc7d 100644 --- a/docs_src/request_files/tutorial001_03.py +++ b/docs_src/request_files/tutorial001_03.py @@ -4,12 +4,12 @@ app = FastAPI() @app.post("/files/") -async def create_file(file: bytes = File(..., description="A file read as bytes")): +async def create_file(file: bytes = File(description="A file read as bytes")): return {"file_size": len(file)} @app.post("/uploadfile/") async def create_upload_file( - file: UploadFile = File(..., description="A file read as UploadFile") + file: UploadFile = File(description="A file read as UploadFile"), ): return {"filename": file.filename} diff --git a/docs_src/request_files/tutorial002.py b/docs_src/request_files/tutorial002.py index 94abb7c6c..b4d0acc68 100644 --- a/docs_src/request_files/tutorial002.py +++ b/docs_src/request_files/tutorial002.py @@ -7,7 +7,7 @@ app = FastAPI() @app.post("/files/") -async def create_files(files: List[bytes] = File(...)): +async def create_files(files: List[bytes] = File()): return {"file_sizes": [len(file) for file in files]} diff --git a/docs_src/request_files/tutorial002_py39.py b/docs_src/request_files/tutorial002_py39.py index 2779618bd..b64cf5598 100644 --- a/docs_src/request_files/tutorial002_py39.py +++ b/docs_src/request_files/tutorial002_py39.py @@ -5,7 +5,7 @@ app = FastAPI() @app.post("/files/") -async def create_files(files: list[bytes] = File(...)): +async def create_files(files: list[bytes] = File()): return {"file_sizes": [len(file) for file in files]} diff --git a/docs_src/request_files/tutorial003.py b/docs_src/request_files/tutorial003.py index 4a91b7a8b..e3f805f60 100644 --- a/docs_src/request_files/tutorial003.py +++ b/docs_src/request_files/tutorial003.py @@ -8,14 +8,14 @@ app = FastAPI() @app.post("/files/") async def create_files( - files: List[bytes] = File(..., description="Multiple files as bytes") + files: List[bytes] = File(description="Multiple files as bytes"), ): return {"file_sizes": [len(file) for file in files]} @app.post("/uploadfiles/") async def create_upload_files( - files: List[UploadFile] = File(..., description="Multiple files as UploadFile") + files: List[UploadFile] = File(description="Multiple files as UploadFile"), ): return {"filenames": [file.filename for file in files]} diff --git a/docs_src/request_files/tutorial003_py39.py b/docs_src/request_files/tutorial003_py39.py index d853f48d1..96f5e8742 100644 --- a/docs_src/request_files/tutorial003_py39.py +++ b/docs_src/request_files/tutorial003_py39.py @@ -6,14 +6,14 @@ app = FastAPI() @app.post("/files/") async def create_files( - files: list[bytes] = File(..., description="Multiple files as bytes") + files: list[bytes] = File(description="Multiple files as bytes"), ): return {"file_sizes": [len(file) for file in files]} @app.post("/uploadfiles/") async def create_upload_files( - files: list[UploadFile] = File(..., description="Multiple files as UploadFile") + files: list[UploadFile] = File(description="Multiple files as UploadFile"), ): return {"filenames": [file.filename for file in files]} diff --git a/docs_src/request_forms/tutorial001.py b/docs_src/request_forms/tutorial001.py index c07e22945..a53770001 100644 --- a/docs_src/request_forms/tutorial001.py +++ b/docs_src/request_forms/tutorial001.py @@ -4,5 +4,5 @@ app = FastAPI() @app.post("/login/") -async def login(username: str = Form(...), password: str = Form(...)): +async def login(username: str = Form(), password: str = Form()): return {"username": username} diff --git a/docs_src/request_forms_and_files/tutorial001.py b/docs_src/request_forms_and_files/tutorial001.py index 5bf3a5bc0..7b5224ce5 100644 --- a/docs_src/request_forms_and_files/tutorial001.py +++ b/docs_src/request_forms_and_files/tutorial001.py @@ -5,7 +5,7 @@ app = FastAPI() @app.post("/files/") async def create_file( - file: bytes = File(...), fileb: UploadFile = File(...), token: str = Form(...) + file: bytes = File(), fileb: UploadFile = File(), token: str = Form() ): return { "file_size": len(file), diff --git a/docs_src/response_directly/tutorial001.py b/docs_src/response_directly/tutorial001.py index 6acdc0fc8..5ab655a8a 100644 --- a/docs_src/response_directly/tutorial001.py +++ b/docs_src/response_directly/tutorial001.py @@ -1,5 +1,5 @@ from datetime import datetime -from typing import Optional +from typing import Union from fastapi import FastAPI from fastapi.encoders import jsonable_encoder @@ -10,7 +10,7 @@ from pydantic import BaseModel class Item(BaseModel): title: str timestamp: datetime - description: Optional[str] = None + description: Union[str, None] = None app = FastAPI() diff --git a/docs_src/response_model/tutorial001.py b/docs_src/response_model/tutorial001.py index 57992ecfc..0f6e03e5b 100644 --- a/docs_src/response_model/tutorial001.py +++ b/docs_src/response_model/tutorial001.py @@ -1,4 +1,4 @@ -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: List[str] = [] diff --git a/docs_src/response_model/tutorial001_py39.py b/docs_src/response_model/tutorial001_py39.py index 37b866864..cdcca39d2 100644 --- a/docs_src/response_model/tutorial001_py39.py +++ b/docs_src/response_model/tutorial001_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None tags: list[str] = [] diff --git a/docs_src/response_model/tutorial002.py b/docs_src/response_model/tutorial002.py index 373317eb9..c68e8b138 100644 --- a/docs_src/response_model/tutorial002.py +++ b/docs_src/response_model/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel, EmailStr @@ -10,7 +10,7 @@ class UserIn(BaseModel): username: str password: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None # Don't do this in production! diff --git a/docs_src/response_model/tutorial003.py b/docs_src/response_model/tutorial003.py index e14026dd8..37e493dcb 100644 --- a/docs_src/response_model/tutorial003.py +++ b/docs_src/response_model/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel, EmailStr @@ -10,13 +10,13 @@ class UserIn(BaseModel): username: str password: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None class UserOut(BaseModel): username: str email: EmailStr - full_name: Optional[str] = None + full_name: Union[str, None] = None @app.post("/user/", response_model=UserOut) diff --git a/docs_src/response_model/tutorial004.py b/docs_src/response_model/tutorial004.py index 1e18f989d..10b48039a 100644 --- a/docs_src/response_model/tutorial004.py +++ b/docs_src/response_model/tutorial004.py @@ -1,4 +1,4 @@ -from typing import List, Optional +from typing import List, Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,7 +8,7 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float tax: float = 10.5 tags: List[str] = [] diff --git a/docs_src/response_model/tutorial004_py39.py b/docs_src/response_model/tutorial004_py39.py index 07ccbbf41..9463b45ec 100644 --- a/docs_src/response_model/tutorial004_py39.py +++ b/docs_src/response_model/tutorial004_py39.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,7 +8,7 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float tax: float = 10.5 tags: list[str] = [] diff --git a/docs_src/response_model/tutorial005.py b/docs_src/response_model/tutorial005.py index 03933d1f7..30eb9f8e3 100644 --- a/docs_src/response_model/tutorial005.py +++ b/docs_src/response_model/tutorial005.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,7 +8,7 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float tax: float = 10.5 diff --git a/docs_src/response_model/tutorial006.py b/docs_src/response_model/tutorial006.py index 629ab8a3a..3ffdb512b 100644 --- a/docs_src/response_model/tutorial006.py +++ b/docs_src/response_model/tutorial006.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,7 +8,7 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float tax: float = 10.5 diff --git a/docs_src/schema_extra_example/tutorial001.py b/docs_src/schema_extra_example/tutorial001.py index fab4d7a44..a5ae28127 100644 --- a/docs_src/schema_extra_example/tutorial001.py +++ b/docs_src/schema_extra_example/tutorial001.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None class Config: schema_extra = { diff --git a/docs_src/schema_extra_example/tutorial002.py b/docs_src/schema_extra_example/tutorial002.py index df3df8854..6de434f81 100644 --- a/docs_src/schema_extra_example/tutorial002.py +++ b/docs_src/schema_extra_example/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import FastAPI from pydantic import BaseModel, Field @@ -7,10 +7,10 @@ app = FastAPI() class Item(BaseModel): - name: str = Field(..., example="Foo") - description: Optional[str] = Field(None, example="A very nice Item") - price: float = Field(..., example=35.4) - tax: Optional[float] = Field(None, example=3.2) + name: str = Field(example="Foo") + description: Union[str, None] = Field(default=None, example="A very nice Item") + price: float = Field(example=35.4) + tax: Union[float, None] = Field(default=None, example=3.2) @app.put("/items/{item_id}") diff --git a/docs_src/schema_extra_example/tutorial002_py310.py b/docs_src/schema_extra_example/tutorial002_py310.py index 4f8f8304e..e84928bb1 100644 --- a/docs_src/schema_extra_example/tutorial002_py310.py +++ b/docs_src/schema_extra_example/tutorial002_py310.py @@ -5,10 +5,10 @@ app = FastAPI() class Item(BaseModel): - name: str = Field(..., example="Foo") - description: str | None = Field(None, example="A very nice Item") - price: float = Field(..., example=35.4) - tax: float | None = Field(None, example=3.2) + name: str = Field(example="Foo") + description: str | None = Field(default=None, example="A very nice Item") + price: float = Field(example=35.4) + tax: float | None = Field(default=None, example=3.2) @app.put("/items/{item_id}") diff --git a/docs_src/schema_extra_example/tutorial003.py b/docs_src/schema_extra_example/tutorial003.py index 58c79f554..ce1736bba 100644 --- a/docs_src/schema_extra_example/tutorial003.py +++ b/docs_src/schema_extra_example/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Body, FastAPI from pydantic import BaseModel @@ -8,16 +8,15 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None @app.put("/items/{item_id}") async def update_item( item_id: int, item: Item = Body( - ..., example={ "name": "Foo", "description": "A very nice Item", diff --git a/docs_src/schema_extra_example/tutorial003_py310.py b/docs_src/schema_extra_example/tutorial003_py310.py index cf4c99dc0..1e137101d 100644 --- a/docs_src/schema_extra_example/tutorial003_py310.py +++ b/docs_src/schema_extra_example/tutorial003_py310.py @@ -15,7 +15,6 @@ class Item(BaseModel): async def update_item( item_id: int, item: Item = Body( - ..., example={ "name": "Foo", "description": "A very nice Item", diff --git a/docs_src/schema_extra_example/tutorial004.py b/docs_src/schema_extra_example/tutorial004.py index 9f0e8b437..b67edf30c 100644 --- a/docs_src/schema_extra_example/tutorial004.py +++ b/docs_src/schema_extra_example/tutorial004.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Body, FastAPI from pydantic import BaseModel @@ -8,9 +8,9 @@ app = FastAPI() class Item(BaseModel): name: str - description: Optional[str] = None + description: Union[str, None] = None price: float - tax: Optional[float] = None + tax: Union[float, None] = None @app.put("/items/{item_id}") @@ -18,7 +18,6 @@ async def update_item( *, item_id: int, item: Item = Body( - ..., examples={ "normal": { "summary": "A normal example", diff --git a/docs_src/schema_extra_example/tutorial004_py310.py b/docs_src/schema_extra_example/tutorial004_py310.py index 6f29c1a5c..100a30860 100644 --- a/docs_src/schema_extra_example/tutorial004_py310.py +++ b/docs_src/schema_extra_example/tutorial004_py310.py @@ -16,7 +16,6 @@ async def update_item( *, item_id: int, item: Item = Body( - ..., examples={ "normal": { "summary": "A normal example", diff --git a/docs_src/security/tutorial002.py b/docs_src/security/tutorial002.py index 03e0cd5fc..bfd035221 100644 --- a/docs_src/security/tutorial002.py +++ b/docs_src/security/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI from fastapi.security import OAuth2PasswordBearer @@ -11,9 +11,9 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token") class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None def fake_decode_token(token): diff --git a/docs_src/security/tutorial003.py b/docs_src/security/tutorial003.py index a6bb176e4..4b324866f 100644 --- a/docs_src/security/tutorial003.py +++ b/docs_src/security/tutorial003.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI, HTTPException, status from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm @@ -33,9 +33,9 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token") class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None class UserInDB(User): diff --git a/docs_src/security/tutorial004.py b/docs_src/security/tutorial004.py index 18e2c428f..64099abe9 100644 --- a/docs_src/security/tutorial004.py +++ b/docs_src/security/tutorial004.py @@ -1,5 +1,5 @@ from datetime import datetime, timedelta -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI, HTTPException, status from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm @@ -31,14 +31,14 @@ class Token(BaseModel): class TokenData(BaseModel): - username: Optional[str] = None + username: Union[str, None] = None class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None class UserInDB(User): @@ -75,7 +75,7 @@ def authenticate_user(fake_db, username: str, password: str): return user -def create_access_token(data: dict, expires_delta: Optional[timedelta] = None): +def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None): to_encode = data.copy() if expires_delta: expire = datetime.utcnow() + expires_delta diff --git a/docs_src/security/tutorial005.py b/docs_src/security/tutorial005.py index 5b34a09f1..ab3af9a6a 100644 --- a/docs_src/security/tutorial005.py +++ b/docs_src/security/tutorial005.py @@ -1,5 +1,5 @@ from datetime import datetime, timedelta -from typing import List, Optional +from typing import List, Union from fastapi import Depends, FastAPI, HTTPException, Security, status from fastapi.security import ( @@ -42,15 +42,15 @@ class Token(BaseModel): class TokenData(BaseModel): - username: Optional[str] = None + username: Union[str, None] = None scopes: List[str] = [] class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None class UserInDB(User): @@ -90,7 +90,7 @@ def authenticate_user(fake_db, username: str, password: str): return user -def create_access_token(data: dict, expires_delta: Optional[timedelta] = None): +def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None): to_encode = data.copy() if expires_delta: expire = datetime.utcnow() + expires_delta diff --git a/docs_src/security/tutorial005_py39.py b/docs_src/security/tutorial005_py39.py index d45c08ce6..38391308a 100644 --- a/docs_src/security/tutorial005_py39.py +++ b/docs_src/security/tutorial005_py39.py @@ -1,5 +1,5 @@ from datetime import datetime, timedelta -from typing import Optional +from typing import Union from fastapi import Depends, FastAPI, HTTPException, Security, status from fastapi.security import ( @@ -42,15 +42,15 @@ class Token(BaseModel): class TokenData(BaseModel): - username: Optional[str] = None + username: Union[str, None] = None scopes: list[str] = [] class User(BaseModel): username: str - email: Optional[str] = None - full_name: Optional[str] = None - disabled: Optional[bool] = None + email: Union[str, None] = None + full_name: Union[str, None] = None + disabled: Union[bool, None] = None class UserInDB(User): @@ -90,7 +90,7 @@ def authenticate_user(fake_db, username: str, password: str): return user -def create_access_token(data: dict, expires_delta: Optional[timedelta] = None): +def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None): to_encode = data.copy() if expires_delta: expire = datetime.utcnow() + expires_delta diff --git a/docs_src/security/tutorial007.py b/docs_src/security/tutorial007.py index 90b9ac054..790ee10bc 100644 --- a/docs_src/security/tutorial007.py +++ b/docs_src/security/tutorial007.py @@ -9,9 +9,17 @@ security = HTTPBasic() def get_current_username(credentials: HTTPBasicCredentials = Depends(security)): - correct_username = secrets.compare_digest(credentials.username, "stanleyjobson") - correct_password = secrets.compare_digest(credentials.password, "swordfish") - if not (correct_username and correct_password): + current_username_bytes = credentials.username.encode("utf8") + correct_username_bytes = b"stanleyjobson" + is_correct_username = secrets.compare_digest( + current_username_bytes, correct_username_bytes + ) + current_password_bytes = credentials.password.encode("utf8") + correct_password_bytes = b"swordfish" + is_correct_password = secrets.compare_digest( + current_password_bytes, correct_password_bytes + ) + if not (is_correct_username and is_correct_password): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect email or password", diff --git a/docs_src/sql_databases/sql_app/schemas.py b/docs_src/sql_databases/sql_app/schemas.py index 51655663a..c49beba88 100644 --- a/docs_src/sql_databases/sql_app/schemas.py +++ b/docs_src/sql_databases/sql_app/schemas.py @@ -1,11 +1,11 @@ -from typing import List, Optional +from typing import List, Union from pydantic import BaseModel class ItemBase(BaseModel): title: str - description: Optional[str] = None + description: Union[str, None] = None class ItemCreate(ItemBase): diff --git a/docs_src/sql_databases/sql_app_py39/schemas.py b/docs_src/sql_databases/sql_app_py39/schemas.py index a19f1cdfe..dadc403d9 100644 --- a/docs_src/sql_databases/sql_app_py39/schemas.py +++ b/docs_src/sql_databases/sql_app_py39/schemas.py @@ -1,11 +1,11 @@ -from typing import Optional +from typing import Union from pydantic import BaseModel class ItemBase(BaseModel): title: str - description: Optional[str] = None + description: Union[str, None] = None class ItemCreate(ItemBase): diff --git a/docs_src/sql_databases_peewee/sql_app/schemas.py b/docs_src/sql_databases_peewee/sql_app/schemas.py index b715604ee..d8775cb30 100644 --- a/docs_src/sql_databases_peewee/sql_app/schemas.py +++ b/docs_src/sql_databases_peewee/sql_app/schemas.py @@ -1,4 +1,4 @@ -from typing import Any, List, Optional +from typing import Any, List, Union import peewee from pydantic import BaseModel @@ -15,7 +15,7 @@ class PeeweeGetterDict(GetterDict): class ItemBase(BaseModel): title: str - description: Optional[str] = None + description: Union[str, None] = None class ItemCreate(ItemBase): diff --git a/docs_src/websockets/tutorial002.py b/docs_src/websockets/tutorial002.py index 53cdb41ff..cf5c7e805 100644 --- a/docs_src/websockets/tutorial002.py +++ b/docs_src/websockets/tutorial002.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Union from fastapi import Cookie, Depends, FastAPI, Query, WebSocket, status from fastapi.responses import HTMLResponse @@ -57,8 +57,8 @@ async def get(): async def get_cookie_or_token( websocket: WebSocket, - session: Optional[str] = Cookie(None), - token: Optional[str] = Query(None), + session: Union[str, None] = Cookie(default=None), + token: Union[str, None] = Query(default=None), ): if session is None and token is None: await websocket.close(code=status.WS_1008_POLICY_VIOLATION) @@ -69,7 +69,7 @@ async def get_cookie_or_token( async def websocket_endpoint( websocket: WebSocket, item_id: str, - q: Optional[int] = None, + q: Union[int, None] = None, cookie_or_token: str = Depends(get_cookie_or_token), ): await websocket.accept() diff --git a/fastapi/__init__.py b/fastapi/__init__.py index 8718788fa..a9b44fc4a 100644 --- a/fastapi/__init__.py +++ b/fastapi/__init__.py @@ -1,6 +1,6 @@ """FastAPI framework, high performance, easy to learn, fast to code, ready for production""" -__version__ = "0.73.0" +__version__ = "0.83.0" from starlette import status as status diff --git a/fastapi/applications.py b/fastapi/applications.py index dbfd76fb9..a242c504c 100644 --- a/fastapi/applications.py +++ b/fastapi/applications.py @@ -1,8 +1,18 @@ from enum import Enum -from typing import Any, Callable, Coroutine, Dict, List, Optional, Sequence, Type, Union +from typing import ( + Any, + Awaitable, + Callable, + Coroutine, + Dict, + List, + Optional, + Sequence, + Type, + Union, +) from fastapi import routing -from fastapi.concurrency import AsyncExitStack from fastapi.datastructures import Default, DefaultPlaceholder from fastapi.encoders import DictIntStrAny, SetIntStr from fastapi.exception_handlers import ( @@ -11,6 +21,7 @@ from fastapi.exception_handlers import ( ) from fastapi.exceptions import RequestValidationError from fastapi.logger import logger +from fastapi.middleware.asyncexitstack import AsyncExitStackMiddleware from fastapi.openapi.docs import ( get_redoc_html, get_swagger_ui_html, @@ -19,10 +30,12 @@ from fastapi.openapi.docs import ( from fastapi.openapi.utils import get_openapi from fastapi.params import Depends from fastapi.types import DecoratedCallable +from fastapi.utils import generate_unique_id from starlette.applications import Starlette from starlette.datastructures import State -from starlette.exceptions import HTTPException +from starlette.exceptions import ExceptionMiddleware, HTTPException from starlette.middleware import Middleware +from starlette.middleware.errors import ServerErrorMiddleware from starlette.requests import Request from starlette.responses import HTMLResponse, JSONResponse, Response from starlette.routing import BaseRoute @@ -67,10 +80,44 @@ class FastAPI(Starlette): deprecated: Optional[bool] = None, include_in_schema: bool = True, swagger_ui_parameters: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), **extra: Any, ) -> None: self._debug: bool = debug + self.title = title + self.description = description + self.version = version + self.terms_of_service = terms_of_service + self.contact = contact + self.license_info = license_info + self.openapi_url = openapi_url + self.openapi_tags = openapi_tags + self.root_path_in_servers = root_path_in_servers + self.docs_url = docs_url + self.redoc_url = redoc_url + self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url + self.swagger_ui_init_oauth = swagger_ui_init_oauth + self.swagger_ui_parameters = swagger_ui_parameters + self.servers = servers or [] + self.extra = extra + self.openapi_version = "3.0.2" + self.openapi_schema: Optional[Dict[str, Any]] = None + if self.openapi_url: + assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'" + assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'" + # TODO: remove when discarding the openapi_prefix parameter + if openapi_prefix: + logger.warning( + '"openapi_prefix" has been deprecated in favor of "root_path", which ' + "follows more closely the ASGI standard, is simpler, and more " + "automatic. Check the docs at " + "https://fastapi.tiangolo.com/advanced/sub-applications/" + ) + self.root_path = root_path or openapi_prefix self.state: State = State() + self.dependency_overrides: Dict[Callable[..., Any], Callable[..., Any]] = {} self.router: routing.APIRouter = routing.APIRouter( routes=routes, dependency_overrides_provider=self, @@ -82,13 +129,11 @@ class FastAPI(Starlette): deprecated=deprecated, include_in_schema=include_in_schema, responses=responses, + generate_unique_id_function=generate_unique_id_function, ) self.exception_handlers: Dict[ - Union[int, Type[Exception]], - Callable[[Request, Any], Coroutine[Any, Any, Response]], - ] = ( - {} if exception_handlers is None else dict(exception_handlers) - ) + Any, Callable[[Request, Any], Union[Response, Awaitable[Response]]] + ] = ({} if exception_handlers is None else dict(exception_handlers)) self.exception_handlers.setdefault(HTTPException, http_exception_handler) self.exception_handlers.setdefault( RequestValidationError, request_validation_exception_handler @@ -98,42 +143,57 @@ class FastAPI(Starlette): [] if middleware is None else list(middleware) ) self.middleware_stack: ASGIApp = self.build_middleware_stack() - - self.title = title - self.description = description - self.version = version - self.terms_of_service = terms_of_service - self.contact = contact - self.license_info = license_info - self.servers = servers or [] - self.openapi_url = openapi_url - self.openapi_tags = openapi_tags - # TODO: remove when discarding the openapi_prefix parameter - if openapi_prefix: - logger.warning( - '"openapi_prefix" has been deprecated in favor of "root_path", which ' - "follows more closely the ASGI standard, is simpler, and more " - "automatic. Check the docs at " - "https://fastapi.tiangolo.com/advanced/sub-applications/" - ) - self.root_path = root_path or openapi_prefix - self.root_path_in_servers = root_path_in_servers - self.docs_url = docs_url - self.redoc_url = redoc_url - self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url - self.swagger_ui_init_oauth = swagger_ui_init_oauth - self.swagger_ui_parameters = swagger_ui_parameters - self.extra = extra - self.dependency_overrides: Dict[Callable[..., Any], Callable[..., Any]] = {} - - self.openapi_version = "3.0.2" - - if self.openapi_url: - assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'" - assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'" - self.openapi_schema: Optional[Dict[str, Any]] = None self.setup() + def build_middleware_stack(self) -> ASGIApp: + # Duplicate/override from Starlette to add AsyncExitStackMiddleware + # inside of ExceptionMiddleware, inside of custom user middlewares + debug = self.debug + error_handler = None + exception_handlers = {} + + for key, value in self.exception_handlers.items(): + if key in (500, Exception): + error_handler = value + else: + exception_handlers[key] = value + + middleware = ( + [Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)] + + self.user_middleware + + [ + Middleware( + ExceptionMiddleware, handlers=exception_handlers, debug=debug + ), + # Add FastAPI-specific AsyncExitStackMiddleware for dependencies with + # contextvars. + # This needs to happen after user middlewares because those create a + # new contextvars context copy by using a new AnyIO task group. + # The initial part of dependencies with yield is executed in the + # FastAPI code, inside all the middlewares, but the teardown part + # (after yield) is executed in the AsyncExitStack in this middleware, + # if the AsyncExitStack lived outside of the custom middlewares and + # contextvars were set in a dependency with yield in that internal + # contextvars context, the values would not be available in the + # outside context of the AsyncExitStack. + # By putting the middleware and the AsyncExitStack here, inside all + # user middlewares, the code before and after yield in dependencies + # with yield is executed in the same contextvars context, so all values + # set in contextvars before yield is still available after yield as + # would be expected. + # Additionally, by having this AsyncExitStack here, after the + # ExceptionMiddleware, now dependencies can catch handled exceptions, + # e.g. HTTPException, to customize the teardown code (e.g. DB session + # rollback). + Middleware(AsyncExitStackMiddleware), + ] + ) + + app = self.router + for cls, options in reversed(middleware): + app = cls(app=app, **options) + return app + def openapi(self) -> Dict[str, Any]: if not self.openapi_schema: self.openapi_schema = get_openapi( @@ -206,19 +266,14 @@ class FastAPI(Starlette): async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: if self.root_path: scope["root_path"] = self.root_path - if AsyncExitStack: - async with AsyncExitStack() as stack: - scope["fastapi_astack"] = stack - await super().__call__(scope, receive, send) - else: - await super().__call__(scope, receive, send) # pragma: no cover + await super().__call__(scope, receive, send) def add_api_route( self, path: str, endpoint: Callable[..., Coroutine[Any, Any, Response]], *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -241,6 +296,9 @@ class FastAPI(Starlette): ), name: Optional[str] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> None: self.router.add_api_route( path, @@ -266,13 +324,14 @@ class FastAPI(Starlette): response_class=response_class, name=name, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def api_route( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -293,6 +352,9 @@ class FastAPI(Starlette): response_class: Type[Response] = Default(JSONResponse), name: Optional[str] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: def decorator(func: DecoratedCallable) -> DecoratedCallable: self.router.add_api_route( @@ -319,6 +381,7 @@ class FastAPI(Starlette): response_class=response_class, name=name, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) return func @@ -350,6 +413,9 @@ class FastAPI(Starlette): include_in_schema: bool = True, default_response_class: Type[Response] = Default(JSONResponse), callbacks: Optional[List[BaseRoute]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> None: self.router.include_router( router, @@ -361,13 +427,14 @@ class FastAPI(Starlette): include_in_schema=include_in_schema, default_response_class=default_response_class, callbacks=callbacks, + generate_unique_id_function=generate_unique_id_function, ) def get( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -388,6 +455,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.get( path, @@ -412,13 +482,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def put( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -439,6 +510,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.put( path, @@ -463,13 +537,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def post( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -490,6 +565,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.post( path, @@ -514,13 +592,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def delete( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -541,6 +620,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.delete( path, @@ -553,10 +635,10 @@ class FastAPI(Starlette): response_description=response_description, responses=responses, deprecated=deprecated, + operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, - operation_id=operation_id, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, @@ -565,13 +647,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def options( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -592,6 +675,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.options( path, @@ -616,13 +702,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def head( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -643,6 +730,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.head( path, @@ -667,13 +757,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def patch( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -694,6 +785,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.patch( path, @@ -718,13 +812,14 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def trace( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[Depends]] = None, @@ -745,6 +840,9 @@ class FastAPI(Starlette): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[routing.APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.router.trace( path, @@ -769,4 +867,5 @@ class FastAPI(Starlette): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) diff --git a/fastapi/concurrency.py b/fastapi/concurrency.py index 04382c69e..c728ec1d2 100644 --- a/fastapi/concurrency.py +++ b/fastapi/concurrency.py @@ -1,6 +1,8 @@ import sys from typing import AsyncGenerator, ContextManager, TypeVar +import anyio +from anyio import CapacityLimiter from starlette.concurrency import iterate_in_threadpool as iterate_in_threadpool # noqa from starlette.concurrency import run_in_threadpool as run_in_threadpool # noqa from starlette.concurrency import ( # noqa @@ -22,11 +24,24 @@ _T = TypeVar("_T") async def contextmanager_in_threadpool( cm: ContextManager[_T], ) -> AsyncGenerator[_T, None]: + # blocking __exit__ from running waiting on a free thread + # can create race conditions/deadlocks if the context manager itself + # has it's own internal pool (e.g. a database connection pool) + # to avoid this we let __exit__ run without a capacity limit + # since we're creating a new limiter for each call, any non-zero limit + # works (1 is arbitrary) + exit_limiter = CapacityLimiter(1) try: yield await run_in_threadpool(cm.__enter__) except Exception as e: - ok = await run_in_threadpool(cm.__exit__, type(e), e, None) + ok = bool( + await anyio.to_thread.run_sync( + cm.__exit__, type(e), e, None, limiter=exit_limiter + ) + ) if not ok: raise e else: - await run_in_threadpool(cm.__exit__, None, None, None) + await anyio.to_thread.run_sync( + cm.__exit__, None, None, None, limiter=exit_limiter + ) diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py index d4028d067..d098b65f1 100644 --- a/fastapi/dependencies/utils.py +++ b/fastapi/dependencies/utils.py @@ -34,6 +34,7 @@ from pydantic import BaseModel, create_model from pydantic.error_wrappers import ErrorWrapper from pydantic.errors import MissingError from pydantic.fields import ( + SHAPE_FROZENSET, SHAPE_LIST, SHAPE_SEQUENCE, SHAPE_SET, @@ -43,6 +44,7 @@ from pydantic.fields import ( FieldInfo, ModelField, Required, + Undefined, ) from pydantic.schema import get_annotation_from_field_info from pydantic.typing import ForwardRef, evaluate_forwardref @@ -57,6 +59,7 @@ from starlette.websockets import WebSocket sequence_shapes = { SHAPE_LIST, SHAPE_SET, + SHAPE_FROZENSET, SHAPE_TUPLE, SHAPE_SEQUENCE, SHAPE_TUPLE_ELLIPSIS, @@ -160,7 +163,6 @@ def get_sub_dependant( ) if security_requirement: sub_dependant.security_requirements.append(security_requirement) - sub_dependant.security_scopes = security_scopes return sub_dependant @@ -277,7 +279,13 @@ def get_dependant( path_param_names = get_path_param_names(path) endpoint_signature = get_typed_signature(call) signature_params = endpoint_signature.parameters - dependant = Dependant(call=call, name=name, path=path, use_cache=use_cache) + dependant = Dependant( + call=call, + name=name, + path=path, + security_scopes=security_scopes, + use_cache=use_cache, + ) for param_name, param in signature_params.items(): if isinstance(param.default, params.Depends): sub_dependant = get_param_sub_dependant( @@ -294,10 +302,7 @@ def get_dependant( assert is_scalar_field( field=param_field ), "Path params must be of one of the supported types" - if isinstance(param.default, params.Path): - ignore_default = False - else: - ignore_default = True + ignore_default = not isinstance(param.default, params.Path) param_field = get_param_field( param=param, param_name=param_name, @@ -316,7 +321,7 @@ def get_dependant( field_info = param_field.field_info assert isinstance( field_info, params.Body - ), f"Param: {param_field.name} can only be a request body, using Body(...)" + ), f"Param: {param_field.name} can only be a request body, using Body()" dependant.body_params.append(param_field) return dependant @@ -353,7 +358,7 @@ def get_param_field( force_type: Optional[params.ParamTypes] = None, ignore_default: bool = False, ) -> ModelField: - default_value = Required + default_value: Any = Undefined had_schema = False if not param.default == param.empty and ignore_default is False: default_value = param.default @@ -369,8 +374,13 @@ def get_param_field( if force_type: field_info.in_ = force_type # type: ignore else: - field_info = default_field_info(default_value) - required = default_value == Required + field_info = default_field_info(default=default_value) + required = True + if default_value is Required or ignore_default: + required = True + default_value = None + elif default_value is not Undefined: + required = False annotation: Any = Any if not param.annotation == param.empty: annotation = param.annotation @@ -382,12 +392,11 @@ def get_param_field( field = create_response_field( name=param.name, type_=annotation, - default=None if required else default_value, + default=default_value, alias=alias, required=required, field_info=field_info, ) - field.required = required if not had_schema and not is_scalar_field(field=field): field.field_info = params.Body(field_info.default) if not had_schema and lenient_issubclass(field.type_, UploadFile): @@ -462,13 +471,10 @@ async def solve_dependencies( ]: values: Dict[str, Any] = {} errors: List[ErrorWrapper] = [] - response = response or Response( - content=None, - status_code=None, # type: ignore - headers=None, # type: ignore # in Starlette - media_type=None, # type: ignore # in Starlette - background=None, # type: ignore # in Starlette - ) + if response is None: + response = Response() + del response.headers["content-length"] + response.status_code = None # type: ignore dependency_cache = dependency_cache or {} sub_dependant: Dependant for sub_dependant in dependant.dependencies: @@ -493,7 +499,6 @@ async def solve_dependencies( name=sub_dependant.name, security_scopes=sub_dependant.security_scopes, ) - use_sub_dependant.security_scopes = sub_dependant.security_scopes solved_result = await solve_dependencies( request=request, diff --git a/fastapi/encoders.py b/fastapi/encoders.py index 4b7ffe313..93045ca27 100644 --- a/fastapi/encoders.py +++ b/fastapi/encoders.py @@ -71,7 +71,18 @@ def jsonable_encoder( sqlalchemy_safe=sqlalchemy_safe, ) if dataclasses.is_dataclass(obj): - return dataclasses.asdict(obj) + obj_dict = dataclasses.asdict(obj) + return jsonable_encoder( + obj_dict, + include=include, + exclude=exclude, + by_alias=by_alias, + exclude_unset=exclude_unset, + exclude_defaults=exclude_defaults, + exclude_none=exclude_none, + custom_encoder=custom_encoder, + sqlalchemy_safe=sqlalchemy_safe, + ) if isinstance(obj, Enum): return obj.value if isinstance(obj, PurePath): @@ -80,6 +91,11 @@ def jsonable_encoder( return obj if isinstance(obj, dict): encoded_dict = {} + allowed_keys = set(obj.keys()) + if include is not None: + allowed_keys &= set(include) + if exclude is not None: + allowed_keys -= set(exclude) for key, value in obj.items(): if ( ( @@ -88,7 +104,7 @@ def jsonable_encoder( or (not key.startswith("_sa")) ) and (value is not None or not exclude_none) - and ((include and key in include) or not exclude or key not in exclude) + and key in allowed_keys ): encoded_key = jsonable_encoder( key, @@ -132,10 +148,10 @@ def jsonable_encoder( if isinstance(obj, classes_tuple): return encoder(obj) - errors: List[Exception] = [] try: data = dict(obj) except Exception as e: + errors: List[Exception] = [] errors.append(e) try: data = vars(obj) @@ -144,6 +160,8 @@ def jsonable_encoder( raise ValueError(errors) return jsonable_encoder( data, + include=include, + exclude=exclude, by_alias=by_alias, exclude_unset=exclude_unset, exclude_defaults=exclude_defaults, diff --git a/fastapi/exception_handlers.py b/fastapi/exception_handlers.py index 2b286d71c..4d7ea5ec2 100644 --- a/fastapi/exception_handlers.py +++ b/fastapi/exception_handlers.py @@ -1,19 +1,19 @@ from fastapi.encoders import jsonable_encoder from fastapi.exceptions import RequestValidationError +from fastapi.utils import is_body_allowed_for_status_code from starlette.exceptions import HTTPException from starlette.requests import Request -from starlette.responses import JSONResponse +from starlette.responses import JSONResponse, Response from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY -async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse: +async def http_exception_handler(request: Request, exc: HTTPException) -> Response: headers = getattr(exc, "headers", None) - if headers: - return JSONResponse( - {"detail": exc.detail}, status_code=exc.status_code, headers=headers - ) - else: - return JSONResponse({"detail": exc.detail}, status_code=exc.status_code) + if not is_body_allowed_for_status_code(exc.status_code): + return Response(status_code=exc.status_code, headers=headers) + return JSONResponse( + {"detail": exc.detail}, status_code=exc.status_code, headers=headers + ) async def request_validation_exception_handler( diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py index f4a837bb4..0f50acc6c 100644 --- a/fastapi/exceptions.py +++ b/fastapi/exceptions.py @@ -12,8 +12,7 @@ class HTTPException(StarletteHTTPException): detail: Any = None, headers: Optional[Dict[str, Any]] = None, ) -> None: - super().__init__(status_code=status_code, detail=detail) - self.headers = headers + super().__init__(status_code=status_code, detail=detail, headers=headers) RequestErrorModel: Type[BaseModel] = create_model("Request") diff --git a/fastapi/middleware/asyncexitstack.py b/fastapi/middleware/asyncexitstack.py new file mode 100644 index 000000000..503a68ac7 --- /dev/null +++ b/fastapi/middleware/asyncexitstack.py @@ -0,0 +1,28 @@ +from typing import Optional + +from fastapi.concurrency import AsyncExitStack +from starlette.types import ASGIApp, Receive, Scope, Send + + +class AsyncExitStackMiddleware: + def __init__(self, app: ASGIApp, context_name: str = "fastapi_astack") -> None: + self.app = app + self.context_name = context_name + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if AsyncExitStack: + dependency_exception: Optional[Exception] = None + async with AsyncExitStack() as stack: + scope[self.context_name] = stack + try: + await self.app(scope, receive, send) + except Exception as e: + dependency_exception = e + raise e + if dependency_exception: + # This exception was possibly handled by the dependency but it should + # still bubble up so that the ServerErrorMiddleware can return a 500 + # or the ExceptionMiddleware can catch and handle any other exceptions + raise dependency_exception + else: + await self.app(scope, receive, send) # pragma: no cover diff --git a/fastapi/openapi/constants.py b/fastapi/openapi/constants.py index 3e69e5524..1897ad750 100644 --- a/fastapi/openapi/constants.py +++ b/fastapi/openapi/constants.py @@ -1,3 +1,2 @@ METHODS_WITH_BODY = {"GET", "HEAD", "POST", "PUT", "DELETE", "PATCH"} -STATUS_CODES_WITH_NO_BODY = {100, 101, 102, 103, 204, 304} REF_PREFIX = "#/components/schemas/" diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py index 1be90d188..bf335118f 100644 --- a/fastapi/openapi/docs.py +++ b/fastapi/openapi/docs.py @@ -17,8 +17,8 @@ def get_swagger_ui_html( *, openapi_url: str, title: str, - swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js", - swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css", + swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui-bundle.js", + swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui.css", swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png", oauth2_redirect_url: Optional[str] = None, init_oauth: Optional[Dict[str, Any]] = None, @@ -106,6 +106,9 @@ def get_redoc_html( + @@ -115,12 +118,14 @@ def get_redoc_html( def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse: + # copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.html html = """ - + - - - + + Swagger UI: OAuth2 Redirect + + + + """ return HTMLResponse(content=html) diff --git a/fastapi/openapi/models.py b/fastapi/openapi/models.py index 9c6598d2d..35aa1672b 100644 --- a/fastapi/openapi/models.py +++ b/fastapi/openapi/models.py @@ -73,7 +73,7 @@ class Server(BaseModel): class Reference(BaseModel): - ref: str = Field(..., alias="$ref") + ref: str = Field(alias="$ref") class Discriminator(BaseModel): @@ -101,28 +101,28 @@ class ExternalDocumentation(BaseModel): class Schema(BaseModel): - ref: Optional[str] = Field(None, alias="$ref") + ref: Optional[str] = Field(default=None, alias="$ref") title: Optional[str] = None multipleOf: Optional[float] = None maximum: Optional[float] = None exclusiveMaximum: Optional[float] = None minimum: Optional[float] = None exclusiveMinimum: Optional[float] = None - maxLength: Optional[int] = Field(None, gte=0) - minLength: Optional[int] = Field(None, gte=0) + maxLength: Optional[int] = Field(default=None, gte=0) + minLength: Optional[int] = Field(default=None, gte=0) pattern: Optional[str] = None - maxItems: Optional[int] = Field(None, gte=0) - minItems: Optional[int] = Field(None, gte=0) + maxItems: Optional[int] = Field(default=None, gte=0) + minItems: Optional[int] = Field(default=None, gte=0) uniqueItems: Optional[bool] = None - maxProperties: Optional[int] = Field(None, gte=0) - minProperties: Optional[int] = Field(None, gte=0) + maxProperties: Optional[int] = Field(default=None, gte=0) + minProperties: Optional[int] = Field(default=None, gte=0) required: Optional[List[str]] = None enum: Optional[List[Any]] = None type: Optional[str] = None allOf: Optional[List["Schema"]] = None oneOf: Optional[List["Schema"]] = None anyOf: Optional[List["Schema"]] = None - not_: Optional["Schema"] = Field(None, alias="not") + not_: Optional["Schema"] = Field(default=None, alias="not") items: Optional[Union["Schema", List["Schema"]]] = None properties: Optional[Dict[str, "Schema"]] = None additionalProperties: Optional[Union["Schema", Reference, bool]] = None @@ -171,7 +171,7 @@ class Encoding(BaseModel): class MediaType(BaseModel): - schema_: Optional[Union[Schema, Reference]] = Field(None, alias="schema") + schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema") example: Optional[Any] = None examples: Optional[Dict[str, Union[Example, Reference]]] = None encoding: Optional[Dict[str, Encoding]] = None @@ -188,7 +188,7 @@ class ParameterBase(BaseModel): style: Optional[str] = None explode: Optional[bool] = None allowReserved: Optional[bool] = None - schema_: Optional[Union[Schema, Reference]] = Field(None, alias="schema") + schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema") example: Optional[Any] = None examples: Optional[Dict[str, Union[Example, Reference]]] = None # Serialization rules for more complex scenarios @@ -200,7 +200,7 @@ class ParameterBase(BaseModel): class Parameter(ParameterBase): name: str - in_: ParameterInType = Field(..., alias="in") + in_: ParameterInType = Field(alias="in") class Header(ParameterBase): @@ -258,7 +258,7 @@ class Operation(BaseModel): class PathItem(BaseModel): - ref: Optional[str] = Field(None, alias="$ref") + ref: Optional[str] = Field(default=None, alias="$ref") summary: Optional[str] = None description: Optional[str] = None get: Optional[Operation] = None @@ -284,7 +284,7 @@ class SecuritySchemeType(Enum): class SecurityBase(BaseModel): - type_: SecuritySchemeType = Field(..., alias="type") + type_: SecuritySchemeType = Field(alias="type") description: Optional[str] = None class Config: @@ -299,7 +299,7 @@ class APIKeyIn(Enum): class APIKey(SecurityBase): type_ = Field(SecuritySchemeType.apiKey, alias="type") - in_: APIKeyIn = Field(..., alias="in") + in_: APIKeyIn = Field(alias="in") name: str diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py index aff76b15e..86e15b46d 100644 --- a/fastapi/openapi/utils.py +++ b/fastapi/openapi/utils.py @@ -1,5 +1,6 @@ import http.client import inspect +import warnings from enum import Enum from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Type, Union, cast @@ -8,11 +9,7 @@ from fastapi.datastructures import DefaultPlaceholder from fastapi.dependencies.models import Dependant from fastapi.dependencies.utils import get_flat_dependant, get_flat_params from fastapi.encoders import jsonable_encoder -from fastapi.openapi.constants import ( - METHODS_WITH_BODY, - REF_PREFIX, - STATUS_CODES_WITH_NO_BODY, -) +from fastapi.openapi.constants import METHODS_WITH_BODY, REF_PREFIX from fastapi.openapi.models import OpenAPI from fastapi.params import Body, Param from fastapi.responses import Response @@ -20,6 +17,7 @@ from fastapi.utils import ( deep_dict_update, generate_operation_id_for_path, get_model_definitions, + is_body_allowed_for_status_code, ) from pydantic import BaseModel from pydantic.fields import ModelField, Undefined @@ -37,7 +35,11 @@ validation_error_definition = { "title": "ValidationError", "type": "object", "properties": { - "loc": {"title": "Location", "type": "array", "items": {"type": "string"}}, + "loc": { + "title": "Location", + "type": "array", + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, }, @@ -140,7 +142,15 @@ def get_openapi_operation_request_body( return request_body_oai -def generate_operation_id(*, route: routing.APIRoute, method: str) -> str: +def generate_operation_id( + *, route: routing.APIRoute, method: str +) -> str: # pragma: nocover + warnings.warn( + "fastapi.openapi.utils.generate_operation_id() was deprecated, " + "it is not used internally, and will be removed soon", + DeprecationWarning, + stacklevel=2, + ) if route.operation_id: return route.operation_id path: str = route.path_format @@ -154,7 +164,7 @@ def generate_operation_summary(*, route: routing.APIRoute, method: str) -> str: def get_openapi_operation_metadata( - *, route: routing.APIRoute, method: str + *, route: routing.APIRoute, method: str, operation_ids: Set[str] ) -> Dict[str, Any]: operation: Dict[str, Any] = {} if route.tags: @@ -162,14 +172,25 @@ def get_openapi_operation_metadata( operation["summary"] = generate_operation_summary(route=route, method=method) if route.description: operation["description"] = route.description - operation["operationId"] = generate_operation_id(route=route, method=method) + operation_id = route.operation_id or route.unique_id + if operation_id in operation_ids: + message = ( + f"Duplicate Operation ID {operation_id} for function " + + f"{route.endpoint.__name__}" + ) + file_name = getattr(route.endpoint, "__globals__", {}).get("__file__") + if file_name: + message += f" at {file_name}" + warnings.warn(message) + operation_ids.add(operation_id) + operation["operationId"] = operation_id if route.deprecated: operation["deprecated"] = route.deprecated return operation def get_openapi_path( - *, route: routing.APIRoute, model_name_map: Dict[type, str] + *, route: routing.APIRoute, model_name_map: Dict[type, str], operation_ids: Set[str] ) -> Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any]]: path = {} security_schemes: Dict[str, Any] = {} @@ -183,7 +204,9 @@ def get_openapi_path( route_response_media_type: Optional[str] = current_response_class.media_type if route.include_in_schema: for method in route.methods: - operation = get_openapi_operation_metadata(route=route, method=method) + operation = get_openapi_operation_metadata( + route=route, method=method, operation_ids=operation_ids + ) parameters: List[Dict[str, Any]] = [] flat_dependant = get_flat_dependant(route.dependant, skip_repeats=True) security_definitions, operation_security = get_openapi_security_definitions( @@ -199,9 +222,18 @@ def get_openapi_path( ) parameters.extend(operation_parameters) if parameters: - operation["parameters"] = list( - {param["name"]: param for param in parameters}.values() - ) + all_parameters = { + (param["in"], param["name"]): param for param in parameters + } + required_parameters = { + (param["in"], param["name"]): param + for param in parameters + if param.get("required") + } + # Make sure required definitions of the same parameter take precedence + # over non-required definitions + all_parameters.update(required_parameters) + operation["parameters"] = list(all_parameters.values()) if method in METHODS_WITH_BODY: request_body_oai = get_openapi_operation_request_body( body_field=route.body_field, model_name_map=model_name_map @@ -217,7 +249,9 @@ def get_openapi_path( cb_security_schemes, cb_definitions, ) = get_openapi_path( - route=callback, model_name_map=model_name_map + route=callback, + model_name_map=model_name_map, + operation_ids=operation_ids, ) callbacks[callback.name] = {callback.path: cb_path} operation["callbacks"] = callbacks @@ -237,9 +271,8 @@ def get_openapi_path( operation.setdefault("responses", {}).setdefault(status_code, {})[ "description" ] = route.response_description - if ( - route_response_media_type - and route.status_code not in STATUS_CODES_WITH_NO_BODY + if route_response_media_type and is_body_allowed_for_status_code( + route.status_code ): response_schema = {"type": "string"} if lenient_issubclass(current_response_class, JSONResponse): @@ -384,6 +417,7 @@ def get_openapi( output["servers"] = servers components: Dict[str, Dict[str, Any]] = {} paths: Dict[str, Dict[str, Any]] = {} + operation_ids: Set[str] = set() flat_models = get_flat_models_from_routes(routes) model_name_map = get_model_name_map(flat_models) definitions = get_model_definitions( @@ -391,7 +425,9 @@ def get_openapi( ) for route in routes: if isinstance(route, routing.APIRoute): - result = get_openapi_path(route=route, model_name_map=model_name_map) + result = get_openapi_path( + route=route, model_name_map=model_name_map, operation_ids=operation_ids + ) if result: path, security_schemes, path_definitions = result if path: diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py index a553a1461..1932ef065 100644 --- a/fastapi/param_functions.py +++ b/fastapi/param_functions.py @@ -5,7 +5,7 @@ from pydantic.fields import Undefined def Path( # noqa: N802 - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -44,7 +44,7 @@ def Path( # noqa: N802 def Query( # noqa: N802 - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -63,7 +63,7 @@ def Query( # noqa: N802 **extra: Any, ) -> Any: return params.Query( - default, + default=default, alias=alias, title=title, description=description, @@ -83,7 +83,7 @@ def Query( # noqa: N802 def Header( # noqa: N802 - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, convert_underscores: bool = True, @@ -103,7 +103,7 @@ def Header( # noqa: N802 **extra: Any, ) -> Any: return params.Header( - default, + default=default, alias=alias, convert_underscores=convert_underscores, title=title, @@ -124,7 +124,7 @@ def Header( # noqa: N802 def Cookie( # noqa: N802 - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -143,7 +143,7 @@ def Cookie( # noqa: N802 **extra: Any, ) -> Any: return params.Cookie( - default, + default=default, alias=alias, title=title, description=description, @@ -163,7 +163,7 @@ def Cookie( # noqa: N802 def Body( # noqa: N802 - default: Any, + default: Any = Undefined, *, embed: bool = False, media_type: str = "application/json", @@ -182,7 +182,7 @@ def Body( # noqa: N802 **extra: Any, ) -> Any: return params.Body( - default, + default=default, embed=embed, media_type=media_type, alias=alias, @@ -202,7 +202,7 @@ def Body( # noqa: N802 def Form( # noqa: N802 - default: Any, + default: Any = Undefined, *, media_type: str = "application/x-www-form-urlencoded", alias: Optional[str] = None, @@ -220,7 +220,7 @@ def Form( # noqa: N802 **extra: Any, ) -> Any: return params.Form( - default, + default=default, media_type=media_type, alias=alias, title=title, @@ -239,7 +239,7 @@ def Form( # noqa: N802 def File( # noqa: N802 - default: Any, + default: Any = Undefined, *, media_type: str = "multipart/form-data", alias: Optional[str] = None, @@ -257,7 +257,7 @@ def File( # noqa: N802 **extra: Any, ) -> Any: return params.File( - default, + default=default, media_type=media_type, alias=alias, title=title, diff --git a/fastapi/params.py b/fastapi/params.py index 042bbd42f..5395b98a3 100644 --- a/fastapi/params.py +++ b/fastapi/params.py @@ -16,7 +16,7 @@ class Param(FieldInfo): def __init__( self, - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -39,7 +39,7 @@ class Param(FieldInfo): self.examples = examples self.include_in_schema = include_in_schema super().__init__( - default, + default=default, alias=alias, title=title, description=description, @@ -62,7 +62,7 @@ class Path(Param): def __init__( self, - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -82,7 +82,7 @@ class Path(Param): ): self.in_ = self.in_ super().__init__( - ..., + default=..., alias=alias, title=title, description=description, @@ -106,7 +106,7 @@ class Query(Param): def __init__( self, - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -125,7 +125,7 @@ class Query(Param): **extra: Any, ): super().__init__( - default, + default=default, alias=alias, title=title, description=description, @@ -149,7 +149,7 @@ class Header(Param): def __init__( self, - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, convert_underscores: bool = True, @@ -170,7 +170,7 @@ class Header(Param): ): self.convert_underscores = convert_underscores super().__init__( - default, + default=default, alias=alias, title=title, description=description, @@ -194,7 +194,7 @@ class Cookie(Param): def __init__( self, - default: Any, + default: Any = Undefined, *, alias: Optional[str] = None, title: Optional[str] = None, @@ -213,7 +213,7 @@ class Cookie(Param): **extra: Any, ): super().__init__( - default, + default=default, alias=alias, title=title, description=description, @@ -235,7 +235,7 @@ class Cookie(Param): class Body(FieldInfo): def __init__( self, - default: Any, + default: Any = Undefined, *, embed: bool = False, media_type: str = "application/json", @@ -258,7 +258,7 @@ class Body(FieldInfo): self.example = example self.examples = examples super().__init__( - default, + default=default, alias=alias, title=title, description=description, @@ -297,7 +297,7 @@ class Form(Body): **extra: Any, ): super().__init__( - default, + default=default, embed=True, media_type=media_type, alias=alias, @@ -337,7 +337,7 @@ class File(Form): **extra: Any, ): super().__init__( - default, + default=default, media_type=media_type, alias=alias, title=title, diff --git a/fastapi/responses.py b/fastapi/responses.py index 6cd793157..88dba96e8 100644 --- a/fastapi/responses.py +++ b/fastapi/responses.py @@ -31,4 +31,6 @@ class ORJSONResponse(JSONResponse): def render(self, content: Any) -> bytes: assert orjson is not None, "orjson must be installed to use ORJSONResponse" - return orjson.dumps(content) + return orjson.dumps( + content, option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY + ) diff --git a/fastapi/routing.py b/fastapi/routing.py index 880e1f51e..a4c25c159 100644 --- a/fastapi/routing.py +++ b/fastapi/routing.py @@ -13,6 +13,7 @@ from typing import ( Optional, Sequence, Set, + Tuple, Type, Union, ) @@ -28,13 +29,13 @@ from fastapi.dependencies.utils import ( ) from fastapi.encoders import DictIntStrAny, SetIntStr, jsonable_encoder from fastapi.exceptions import RequestValidationError, WebSocketRequestValidationError -from fastapi.openapi.constants import STATUS_CODES_WITH_NO_BODY from fastapi.types import DecoratedCallable from fastapi.utils import ( create_cloned_field, create_response_field, - generate_operation_id_for_path, + generate_unique_id, get_value_or_default, + is_body_allowed_for_status_code, ) from pydantic import BaseModel from pydantic.error_wrappers import ErrorWrapper, ValidationError @@ -44,7 +45,7 @@ from starlette.concurrency import run_in_threadpool from starlette.exceptions import HTTPException from starlette.requests import Request from starlette.responses import JSONResponse, Response -from starlette.routing import BaseRoute +from starlette.routing import BaseRoute, Match from starlette.routing import Mount as Mount # noqa from starlette.routing import ( compile_path, @@ -53,7 +54,7 @@ from starlette.routing import ( websocket_session, ) from starlette.status import WS_1008_POLICY_VIOLATION -from starlette.types import ASGIApp +from starlette.types import ASGIApp, Scope from starlette.websockets import WebSocket @@ -126,7 +127,7 @@ async def serialize_response( if is_coroutine: value, errors_ = field.validate(response_content, {}, loc=("response",)) else: - value, errors_ = await run_in_threadpool( + value, errors_ = await run_in_threadpool( # type: ignore[misc] field.validate, response_content, {}, loc=("response",) ) if isinstance(errors_, ErrorWrapper): @@ -208,7 +209,11 @@ def get_request_handler( else: body = body_bytes except json.JSONDecodeError as e: - raise RequestValidationError([ErrorWrapper(e, ("body", e.pos))], body=e.doc) + raise RequestValidationError( + [ErrorWrapper(e, ("body", e.pos))], body=e.doc + ) from e + except HTTPException: + raise except Exception as e: raise HTTPException( status_code=400, detail="There was an error parsing the body" @@ -231,7 +236,17 @@ def get_request_handler( if raw_response.background is None: raw_response.background = background_tasks return raw_response - response_data = await serialize_response( + response_args: Dict[str, Any] = {"background": background_tasks} + # If status_code was set, use it, otherwise use the default from the + # response class, in the case of redirect it's 307 + current_status_code = ( + status_code if status_code else sub_response.status_code + ) + if current_status_code is not None: + response_args["status_code"] = current_status_code + if sub_response.status_code: + response_args["status_code"] = sub_response.status_code + content = await serialize_response( field=response_field, response_content=raw_response, include=response_model_include, @@ -242,15 +257,10 @@ def get_request_handler( exclude_none=response_model_exclude_none, is_coroutine=is_coroutine, ) - response_args: Dict[str, Any] = {"background": background_tasks} - # If status_code was set, use it, otherwise use the default from the - # response class, in the case of redirect it's 307 - if status_code is not None: - response_args["status_code"] = status_code - response = actual_response_class(response_data, **response_args) + response = actual_response_class(content, **response_args) + if not is_body_allowed_for_status_code(response.status_code): + response.body = b"" response.headers.raw.extend(sub_response.headers.raw) - if sub_response.status_code: - response.status_code = sub_response.status_code return response return app @@ -287,14 +297,20 @@ class APIWebSocketRoute(routing.WebSocketRoute): self.path = path self.endpoint = endpoint self.name = get_name(endpoint) if name is None else name - self.dependant = get_dependant(path=path, call=self.endpoint) + self.path_regex, self.path_format, self.param_convertors = compile_path(path) + self.dependant = get_dependant(path=self.path_format, call=self.endpoint) self.app = websocket_session( get_websocket_app( dependant=self.dependant, dependency_overrides_provider=dependency_overrides_provider, ) ) - self.path_regex, self.path_format, self.param_convertors = compile_path(path) + + def matches(self, scope: Scope) -> Tuple[Match, Scope]: + match, child_scope = super().matches(scope) + if match != Match.NONE: + child_scope["route"] = self + return match, child_scope class APIRoute(routing.Route): @@ -303,7 +319,7 @@ class APIRoute(routing.Route): path: str, endpoint: Callable[..., Any], *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -328,24 +344,50 @@ class APIRoute(routing.Route): dependency_overrides_provider: Optional[Any] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Union[ + Callable[["APIRoute"], str], DefaultPlaceholder + ] = Default(generate_unique_id), ) -> None: - # normalise enums e.g. http.HTTPStatus - if isinstance(status_code, IntEnum): - status_code = int(status_code) self.path = path self.endpoint = endpoint + self.response_model = response_model + self.summary = summary + self.response_description = response_description + self.deprecated = deprecated + self.operation_id = operation_id + self.response_model_include = response_model_include + self.response_model_exclude = response_model_exclude + self.response_model_by_alias = response_model_by_alias + self.response_model_exclude_unset = response_model_exclude_unset + self.response_model_exclude_defaults = response_model_exclude_defaults + self.response_model_exclude_none = response_model_exclude_none + self.include_in_schema = include_in_schema + self.response_class = response_class + self.dependency_overrides_provider = dependency_overrides_provider + self.callbacks = callbacks + self.openapi_extra = openapi_extra + self.generate_unique_id_function = generate_unique_id_function + self.tags = tags or [] + self.responses = responses or {} self.name = get_name(endpoint) if name is None else name self.path_regex, self.path_format, self.param_convertors = compile_path(path) if methods is None: methods = ["GET"] - self.methods: Set[str] = set([method.upper() for method in methods]) - self.unique_id = generate_operation_id_for_path( - name=self.name, path=self.path_format, method=list(methods)[0] - ) - self.response_model = response_model + self.methods: Set[str] = {method.upper() for method in methods} + if isinstance(generate_unique_id_function, DefaultPlaceholder): + current_generate_unique_id: Callable[ + ["APIRoute"], str + ] = generate_unique_id_function.value + else: + current_generate_unique_id = generate_unique_id_function + self.unique_id = self.operation_id or current_generate_unique_id(self) + # normalize enums e.g. http.HTTPStatus + if isinstance(status_code, IntEnum): + status_code = int(status_code) + self.status_code = status_code if self.response_model: - assert ( - status_code not in STATUS_CODES_WITH_NO_BODY + assert is_body_allowed_for_status_code( + status_code ), f"Status code {status_code} must not have a response body" response_name = "Response_" + self.unique_id self.response_field = create_response_field( @@ -364,26 +406,21 @@ class APIRoute(routing.Route): else: self.response_field = None # type: ignore self.secure_cloned_response_field = None - self.status_code = status_code - self.tags = tags or [] if dependencies: self.dependencies = list(dependencies) else: self.dependencies = [] - self.summary = summary self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "") # if a "form feed" character (page break) is found in the description text, # truncate description text to the content preceding the first "form feed" - self.description = self.description.split("\f")[0] - self.response_description = response_description - self.responses = responses or {} + self.description = self.description.split("\f")[0].strip() response_fields = {} for additional_status_code, response in self.responses.items(): assert isinstance(response, dict), "An additional response must be a dict" model = response.get("model") if model: - assert ( - additional_status_code not in STATUS_CODES_WITH_NO_BODY + assert is_body_allowed_for_status_code( + additional_status_code ), f"Status code {additional_status_code} must not have a response body" response_name = f"Response_{additional_status_code}_{self.unique_id}" response_field = create_response_field(name=response_name, type_=model) @@ -392,16 +429,6 @@ class APIRoute(routing.Route): self.response_fields: Dict[Union[int, str], ModelField] = response_fields else: self.response_fields = {} - self.deprecated = deprecated - self.operation_id = operation_id - self.response_model_include = response_model_include - self.response_model_exclude = response_model_exclude - self.response_model_by_alias = response_model_by_alias - self.response_model_exclude_unset = response_model_exclude_unset - self.response_model_exclude_defaults = response_model_exclude_defaults - self.response_model_exclude_none = response_model_exclude_none - self.include_in_schema = include_in_schema - self.response_class = response_class assert callable(endpoint), "An endpoint must be a callable" self.dependant = get_dependant(path=self.path_format, call=self.endpoint) @@ -411,10 +438,7 @@ class APIRoute(routing.Route): get_parameterless_sub_dependant(depends=depends, path=self.path_format), ) self.body_field = get_body_field(dependant=self.dependant, name=self.unique_id) - self.dependency_overrides_provider = dependency_overrides_provider - self.callbacks = callbacks self.app = request_response(self.get_route_handler()) - self.openapi_extra = openapi_extra def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]: return get_request_handler( @@ -432,6 +456,12 @@ class APIRoute(routing.Route): dependency_overrides_provider=self.dependency_overrides_provider, ) + def matches(self, scope: Scope) -> Tuple[Match, Scope]: + match, child_scope = super().matches(scope) + if match != Match.NONE: + child_scope["route"] = self + return match, child_scope + class APIRouter(routing.Router): def __init__( @@ -452,13 +482,16 @@ class APIRouter(routing.Router): on_shutdown: Optional[Sequence[Callable[[], Any]]] = None, deprecated: Optional[bool] = None, include_in_schema: bool = True, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> None: super().__init__( - routes=routes, # type: ignore # in Starlette + routes=routes, redirect_slashes=redirect_slashes, - default=default, # type: ignore # in Starlette - on_startup=on_startup, # type: ignore # in Starlette - on_shutdown=on_shutdown, # type: ignore # in Starlette + default=default, + on_startup=on_startup, + on_shutdown=on_shutdown, ) if prefix: assert prefix.startswith("/"), "A path prefix must start with '/'" @@ -477,13 +510,14 @@ class APIRouter(routing.Router): self.dependency_overrides_provider = dependency_overrides_provider self.route_class = route_class self.default_response_class = default_response_class + self.generate_unique_id_function = generate_unique_id_function def add_api_route( self, path: str, endpoint: Callable[..., Any], *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -508,6 +542,9 @@ class APIRouter(routing.Router): route_class_override: Optional[Type[APIRoute]] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Union[ + Callable[[APIRoute], str], DefaultPlaceholder + ] = Default(generate_unique_id), ) -> None: route_class = route_class_override or self.route_class responses = responses or {} @@ -525,6 +562,9 @@ class APIRouter(routing.Router): current_callbacks = self.callbacks.copy() if callbacks: current_callbacks.extend(callbacks) + current_generate_unique_id = get_value_or_default( + generate_unique_id_function, self.generate_unique_id_function + ) route = route_class( self.prefix + path, endpoint=endpoint, @@ -551,6 +591,7 @@ class APIRouter(routing.Router): dependency_overrides_provider=self.dependency_overrides_provider, callbacks=current_callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=current_generate_unique_id, ) self.routes.append(route) @@ -558,7 +599,7 @@ class APIRouter(routing.Router): self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -580,6 +621,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_api_route( @@ -607,6 +651,7 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) return func @@ -616,7 +661,7 @@ class APIRouter(routing.Router): self, path: str, endpoint: Callable[..., Any], name: Optional[str] = None ) -> None: route = APIWebSocketRoute( - path, + self.prefix + path, endpoint=endpoint, name=name, dependency_overrides_provider=self.dependency_overrides_provider, @@ -644,6 +689,9 @@ class APIRouter(routing.Router): callbacks: Optional[List[BaseRoute]] = None, deprecated: Optional[bool] = None, include_in_schema: bool = True, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> None: if prefix: assert prefix.startswith("/"), "A path prefix must start with '/'" @@ -685,6 +733,12 @@ class APIRouter(routing.Router): current_callbacks.extend(callbacks) if route.callbacks: current_callbacks.extend(route.callbacks) + current_generate_unique_id = get_value_or_default( + route.generate_unique_id_function, + router.generate_unique_id_function, + generate_unique_id_function, + self.generate_unique_id_function, + ) self.add_api_route( prefix + route.path, route.endpoint, @@ -713,9 +767,10 @@ class APIRouter(routing.Router): route_class_override=type(route), callbacks=current_callbacks, openapi_extra=route.openapi_extra, + generate_unique_id_function=current_generate_unique_id, ) elif isinstance(route, routing.Route): - methods = list(route.methods or []) # type: ignore # in Starlette + methods = list(route.methods or []) self.add_route( prefix + route.path, route.endpoint, @@ -740,7 +795,7 @@ class APIRouter(routing.Router): self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -761,6 +816,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -786,13 +844,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def put( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -813,6 +872,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -838,13 +900,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def post( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -865,6 +928,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -890,13 +956,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def delete( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -917,6 +984,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -942,13 +1012,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def options( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -969,6 +1040,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -994,13 +1068,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def head( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -1021,6 +1096,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -1046,13 +1124,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def patch( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -1073,6 +1152,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( path=path, @@ -1098,13 +1180,14 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) def trace( self, path: str, *, - response_model: Optional[Type[Any]] = None, + response_model: Any = None, status_code: Optional[int] = None, tags: Optional[List[Union[str, Enum]]] = None, dependencies: Optional[Sequence[params.Depends]] = None, @@ -1125,6 +1208,9 @@ class APIRouter(routing.Router): name: Optional[str] = None, callbacks: Optional[List[BaseRoute]] = None, openapi_extra: Optional[Dict[str, Any]] = None, + generate_unique_id_function: Callable[[APIRoute], str] = Default( + generate_unique_id + ), ) -> Callable[[DecoratedCallable], DecoratedCallable]: return self.api_route( @@ -1151,4 +1237,5 @@ class APIRouter(routing.Router): name=name, callbacks=callbacks, openapi_extra=openapi_extra, + generate_unique_id_function=generate_unique_id_function, ) diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py index bdc6e2ea9..653c3010e 100644 --- a/fastapi/security/oauth2.py +++ b/fastapi/security/oauth2.py @@ -45,12 +45,12 @@ class OAuth2PasswordRequestForm: def __init__( self, - grant_type: str = Form(None, regex="password"), - username: str = Form(...), - password: str = Form(...), - scope: str = Form(""), - client_id: Optional[str] = Form(None), - client_secret: Optional[str] = Form(None), + grant_type: str = Form(default=None, regex="password"), + username: str = Form(), + password: str = Form(), + scope: str = Form(default=""), + client_id: Optional[str] = Form(default=None), + client_secret: Optional[str] = Form(default=None), ): self.grant_type = grant_type self.username = username @@ -95,12 +95,12 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): def __init__( self, - grant_type: str = Form(..., regex="password"), - username: str = Form(...), - password: str = Form(...), - scope: str = Form(""), - client_id: Optional[str] = Form(None), - client_secret: Optional[str] = Form(None), + grant_type: str = Form(regex="password"), + username: str = Form(), + password: str = Form(), + scope: str = Form(default=""), + client_id: Optional[str] = Form(default=None), + client_secret: Optional[str] = Form(default=None), ): super().__init__( grant_type=grant_type, @@ -119,7 +119,7 @@ class OAuth2(SecurityBase): flows: Union[OAuthFlowsModel, Dict[str, Dict[str, Any]]] = OAuthFlowsModel(), scheme_name: Optional[str] = None, description: Optional[str] = None, - auto_error: Optional[bool] = True + auto_error: bool = True ): self.model = OAuth2Model(flows=flows, description=description) self.scheme_name = scheme_name or self.__class__.__name__ diff --git a/fastapi/utils.py b/fastapi/utils.py index 8913d85b2..89f54453b 100644 --- a/fastapi/utils.py +++ b/fastapi/utils.py @@ -1,8 +1,9 @@ import functools import re +import warnings from dataclasses import is_dataclass from enum import Enum -from typing import Any, Dict, Optional, Set, Type, Union, cast +from typing import TYPE_CHECKING, Any, Dict, Optional, Set, Type, Union, cast import fastapi from fastapi.datastructures import DefaultPlaceholder, DefaultType @@ -13,6 +14,16 @@ from pydantic.fields import FieldInfo, ModelField, UndefinedType from pydantic.schema import model_process_schema from pydantic.utils import lenient_issubclass +if TYPE_CHECKING: # pragma: nocover + from .routing import APIRoute + + +def is_body_allowed_for_status_code(status_code: Union[int, str, None]) -> bool: + if status_code is None: + return True + current_status_code = int(status_code) + return not (current_status_code < 200 or current_status_code in {204, 304}) + def get_model_definitions( *, @@ -26,6 +37,8 @@ def get_model_definitions( ) definitions.update(m_definitions) model_name = model_name_map[model] + if "description" in m_schema: + m_schema["description"] = m_schema["description"].split("\f")[0] definitions[model_name] = m_schema return definitions @@ -39,7 +52,7 @@ def create_response_field( type_: Type[Any], class_validators: Optional[Dict[str, Validator]] = None, default: Optional[Any] = None, - required: Union[bool, UndefinedType] = False, + required: Union[bool, UndefinedType] = True, model_config: Type[BaseConfig] = BaseConfig, field_info: Optional[FieldInfo] = None, alias: Optional[str] = None, @@ -48,7 +61,7 @@ def create_response_field( Create a new response field. Raises if type_ is invalid. """ class_validators = class_validators or {} - field_info = field_info or FieldInfo(None) + field_info = field_info or FieldInfo() response_field = functools.partial( ModelField, @@ -76,7 +89,7 @@ def create_cloned_field( ) -> ModelField: # _cloned_types has already cloned types, to support recursive models if cloned_types is None: - cloned_types = dict() + cloned_types = {} original_type = field.type_ if is_dataclass(original_type) and hasattr(original_type, "__pydantic_model__"): original_type = original_type.__pydantic_model__ @@ -119,23 +132,45 @@ def create_cloned_field( return new_field -def generate_operation_id_for_path(*, name: str, path: str, method: str) -> str: +def generate_operation_id_for_path( + *, name: str, path: str, method: str +) -> str: # pragma: nocover + warnings.warn( + "fastapi.utils.generate_operation_id_for_path() was deprecated, " + "it is not used internally, and will be removed soon", + DeprecationWarning, + stacklevel=2, + ) operation_id = name + path - operation_id = re.sub("[^0-9a-zA-Z_]", "_", operation_id) + operation_id = re.sub(r"\W", "_", operation_id) operation_id = operation_id + "_" + method.lower() return operation_id +def generate_unique_id(route: "APIRoute") -> str: + operation_id = route.name + route.path_format + operation_id = re.sub(r"\W", "_", operation_id) + assert route.methods + operation_id = operation_id + "_" + list(route.methods)[0].lower() + return operation_id + + def deep_dict_update(main_dict: Dict[Any, Any], update_dict: Dict[Any, Any]) -> None: - for key in update_dict: + for key, value in update_dict.items(): if ( key in main_dict and isinstance(main_dict[key], dict) - and isinstance(update_dict[key], dict) + and isinstance(value, dict) ): - deep_dict_update(main_dict[key], update_dict[key]) + deep_dict_update(main_dict[key], value) + elif ( + key in main_dict + and isinstance(main_dict[key], list) + and isinstance(update_dict[key], list) + ): + main_dict[key] = main_dict[key] + update_dict[key] else: - main_dict[key] = update_dict[key] + main_dict[key] = value def get_value_or_default( diff --git a/fastapi/websockets.py b/fastapi/websockets.py index bed672acf..55a4ac4a1 100644 --- a/fastapi/websockets.py +++ b/fastapi/websockets.py @@ -1,2 +1,3 @@ from starlette.websockets import WebSocket as WebSocket # noqa from starlette.websockets import WebSocketDisconnect as WebSocketDisconnect # noqa +from starlette.websockets import WebSocketState as WebSocketState # noqa diff --git a/pending_tests/main.py b/pending_tests/main.py deleted file mode 100644 index 5e919f1bc..000000000 --- a/pending_tests/main.py +++ /dev/null @@ -1,118 +0,0 @@ -from fastapi import ( - Body, - Cookie, - Depends, - FastAPI, - File, - Form, - Header, - Path, - Query, - Security, -) -from fastapi.security import ( - HTTPBasic, - OAuth2, - OAuth2PasswordBearer, - OAuth2PasswordRequestForm, -) -from pydantic import BaseModel -from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse -from starlette.status import HTTP_202_ACCEPTED - -app = FastAPI() - - -@app.get("/security") -def get_security(sec=Security(HTTPBasic())): - return sec - - -reusable_oauth2 = OAuth2( - flows={ - "password": { - "tokenUrl": "token", - "scopes": {"read:user": "Read a User", "write:user": "Create a user"}, - } - } -) - - -@app.get("/security/oauth2") -def get_security_oauth2(sec=Security(reusable_oauth2, scopes=["read:user"])): - return sec - - -@app.post("/token") -def post_token(request_data: OAuth2PasswordRequestForm = Form(...)): - data = request_data.parse() - access_token = data.username + ":" + data.password - return {"access_token": access_token} - - -class Item(BaseModel): - name: str - price: float - is_offer: bool - - -class FakeDB: - def __init__(self): - self.data = { - "johndoe": { - "username": "johndoe", - "password": "shouldbehashed", - "first_name": "John", - "last_name": "Doe", - } - } - - -class DBConnectionManager: - def __init__(self): - self.db = FakeDB() - - def __call__(self): - return self.db - - -connection_manager = DBConnectionManager() - - -class TokenUserData(BaseModel): - username: str - password: str - - -class UserInDB(BaseModel): - username: str - password: str - first_name: str - last_name: str - - -def require_token( - token: str = Security(reusable_oauth2, scopes=["read:user", "write:user"]) -): - raw_token = token.replace("Bearer ", "") - # Never do this plaintext password usage in production - username, password = raw_token.split(":") - return TokenUserData(username=username, password=password) - - -def require_user( - db: FakeDB = Depends(connection_manager), - user_data: TokenUserData = Depends(require_token), -): - return db.data[user_data.username] - - -class UserOut(BaseModel): - username: str - first_name: str - last_name: str - - -@app.get("/dependency", response_model=UserOut) -def get_dependency(user: UserInDB = Depends(require_user)): - return user diff --git a/pyproject.toml b/pyproject.toml index 77c01322f..3b77b113b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,7 +35,7 @@ classifiers = [ "Topic :: Internet :: WWW/HTTP", ] requires = [ - "starlette ==0.17.1", + "starlette==0.19.1", "pydantic >=1.6.2,!=1.7,!=1.7.1,!=1.7.2,!=1.7.3,!=1.8,!=1.8.1,<2.0.0", ] description-file = "README.md" @@ -49,8 +49,8 @@ test = [ "pytest >=6.2.4,<7.0.0", "pytest-cov >=2.12.0,<4.0.0", "mypy ==0.910", - "flake8 >=3.8.3,<4.0.0", - "black ==21.9b0", + "flake8 >=3.8.3,<6.0.0", + "black == 22.3.0", "isort >=5.0.6,<6.0.0", "requests >=2.24.0,<3.0.0", "httpx >=0.14.0,<0.19.0", @@ -59,41 +59,44 @@ test = [ "peewee >=3.13.3,<4.0.0", "databases[sqlite] >=0.3.2,<0.6.0", "orjson >=3.2.1,<4.0.0", - "ujson >=4.0.1,<5.0.0", + "ujson >=4.0.1,!=4.0.2,!=4.1.0,!=4.2.0,!=4.3.0,!=5.0.0,!=5.1.0,<6.0.0", "python-multipart >=0.0.5,<0.0.6", "flask >=1.1.2,<3.0.0", "anyio[trio] >=3.2.1,<4.0.0", # types - "types-ujson ==0.1.1", - "types-orjson ==3.6.0", - "types-dataclasses ==0.1.7; python_version<'3.7'", + "types-ujson ==4.2.1", + "types-orjson ==3.6.2", + "types-dataclasses ==0.6.5; python_version<'3.7'", ] doc = [ "mkdocs >=1.1.2,<2.0.0", "mkdocs-material >=8.1.4,<9.0.0", "mdx-include >=1.4.1,<2.0.0", "mkdocs-markdownextradata-plugin >=0.1.7,<0.3.0", - "typer-cli >=0.0.12,<0.0.13", - "pyyaml >=5.3.1,<6.0.0" + # TODO: upgrade and enable typer-cli once it supports Click 8.x.x + # "typer-cli >=0.0.12,<0.0.13", + "typer >=0.4.1,<0.5.0", + "pyyaml >=5.3.1,<7.0.0", ] dev = [ "python-jose[cryptography] >=3.3.0,<4.0.0", "passlib[bcrypt] >=1.7.2,<2.0.0", "autoflake >=1.4.0,<2.0.0", - "flake8 >=3.8.3,<4.0.0", - "uvicorn[standard] >=0.12.0,<0.16.0", + "flake8 >=3.8.3,<6.0.0", + "uvicorn[standard] >=0.12.0,<0.18.0", + "pre-commit >=2.17.0,<3.0.0", ] all = [ "requests >=2.24.0,<3.0.0", "jinja2 >=2.11.2,<4.0.0", "python-multipart >=0.0.5,<0.0.6", "itsdangerous >=1.1.0,<3.0.0", - "pyyaml >=5.3.1,<6.0.0", - "ujson >=4.0.1,<5.0.0", + "pyyaml >=5.3.1,<7.0.0", + "ujson >=4.0.1,!=4.0.2,!=4.1.0,!=4.2.0,!=4.3.0,!=5.0.0,!=5.1.0,<6.0.0", "orjson >=3.2.1,<4.0.0", "email_validator >=1.1.1,<2.0.0", - "uvicorn[standard] >=0.12.0,<0.16.0", + "uvicorn[standard] >=0.12.0,<0.18.0", ] [tool.isort] @@ -101,21 +104,7 @@ profile = "black" known_third_party = ["fastapi", "pydantic", "starlette"] [tool.mypy] -# --strict -disallow_any_generics = true -disallow_subclassing_any = true -disallow_untyped_calls = true -disallow_untyped_defs = true -disallow_incomplete_defs = true -check_untyped_defs = true -disallow_untyped_decorators = true -no_implicit_optional = true -warn_redundant_casts = true -warn_unused_ignores = true -warn_return_any = true -implicit_reexport = false -strict_equality = true -# --strict end +strict = true [[tool.mypy.overrides]] module = "fastapi.concurrency" @@ -138,4 +127,7 @@ filterwarnings = [ "error", # TODO: needed by asyncio in Python 3.9.7 https://bugs.python.org/issue45097, try to remove on 3.9.8 'ignore:The loop argument is deprecated since Python 3\.8, and scheduled for removal in Python 3\.10:DeprecationWarning:asyncio', + 'ignore:starlette.middleware.wsgi is deprecated and will be removed in a future release\..*:DeprecationWarning:starlette', + # TODO: remove after dropping support for Python 3.6 + 'ignore:Python 3.6 is no longer supported by the Python core team. Therefore, support for it is deprecated in cryptography and will be removed in a future release.:UserWarning:jose', ] diff --git a/tests/main.py b/tests/main.py index d5603d0e6..fce665704 100644 --- a/tests/main.py +++ b/tests/main.py @@ -1,5 +1,5 @@ import http -from typing import Optional +from typing import FrozenSet, Optional from fastapi import FastAPI, Path, Query @@ -49,97 +49,97 @@ def get_bool_id(item_id: bool): @app.get("/path/param/{item_id}") -def get_path_param_id(item_id: Optional[str] = Path(None)): +def get_path_param_id(item_id: str = Path()): return item_id @app.get("/path/param-required/{item_id}") -def get_path_param_required_id(item_id: str = Path(...)): +def get_path_param_required_id(item_id: str = Path()): return item_id @app.get("/path/param-minlength/{item_id}") -def get_path_param_min_length(item_id: str = Path(..., min_length=3)): +def get_path_param_min_length(item_id: str = Path(min_length=3)): return item_id @app.get("/path/param-maxlength/{item_id}") -def get_path_param_max_length(item_id: str = Path(..., max_length=3)): +def get_path_param_max_length(item_id: str = Path(max_length=3)): return item_id @app.get("/path/param-min_maxlength/{item_id}") -def get_path_param_min_max_length(item_id: str = Path(..., max_length=3, min_length=2)): +def get_path_param_min_max_length(item_id: str = Path(max_length=3, min_length=2)): return item_id @app.get("/path/param-gt/{item_id}") -def get_path_param_gt(item_id: float = Path(..., gt=3)): +def get_path_param_gt(item_id: float = Path(gt=3)): return item_id @app.get("/path/param-gt0/{item_id}") -def get_path_param_gt0(item_id: float = Path(..., gt=0)): +def get_path_param_gt0(item_id: float = Path(gt=0)): return item_id @app.get("/path/param-ge/{item_id}") -def get_path_param_ge(item_id: float = Path(..., ge=3)): +def get_path_param_ge(item_id: float = Path(ge=3)): return item_id @app.get("/path/param-lt/{item_id}") -def get_path_param_lt(item_id: float = Path(..., lt=3)): +def get_path_param_lt(item_id: float = Path(lt=3)): return item_id @app.get("/path/param-lt0/{item_id}") -def get_path_param_lt0(item_id: float = Path(..., lt=0)): +def get_path_param_lt0(item_id: float = Path(lt=0)): return item_id @app.get("/path/param-le/{item_id}") -def get_path_param_le(item_id: float = Path(..., le=3)): +def get_path_param_le(item_id: float = Path(le=3)): return item_id @app.get("/path/param-lt-gt/{item_id}") -def get_path_param_lt_gt(item_id: float = Path(..., lt=3, gt=1)): +def get_path_param_lt_gt(item_id: float = Path(lt=3, gt=1)): return item_id @app.get("/path/param-le-ge/{item_id}") -def get_path_param_le_ge(item_id: float = Path(..., le=3, ge=1)): +def get_path_param_le_ge(item_id: float = Path(le=3, ge=1)): return item_id @app.get("/path/param-lt-int/{item_id}") -def get_path_param_lt_int(item_id: int = Path(..., lt=3)): +def get_path_param_lt_int(item_id: int = Path(lt=3)): return item_id @app.get("/path/param-gt-int/{item_id}") -def get_path_param_gt_int(item_id: int = Path(..., gt=3)): +def get_path_param_gt_int(item_id: int = Path(gt=3)): return item_id @app.get("/path/param-le-int/{item_id}") -def get_path_param_le_int(item_id: int = Path(..., le=3)): +def get_path_param_le_int(item_id: int = Path(le=3)): return item_id @app.get("/path/param-ge-int/{item_id}") -def get_path_param_ge_int(item_id: int = Path(..., ge=3)): +def get_path_param_ge_int(item_id: int = Path(ge=3)): return item_id @app.get("/path/param-lt-gt-int/{item_id}") -def get_path_param_lt_gt_int(item_id: int = Path(..., lt=3, gt=1)): +def get_path_param_lt_gt_int(item_id: int = Path(lt=3, gt=1)): return item_id @app.get("/path/param-le-ge-int/{item_id}") -def get_path_param_le_ge_int(item_id: int = Path(..., le=3, ge=1)): +def get_path_param_le_ge_int(item_id: int = Path(le=3, ge=1)): return item_id @@ -173,22 +173,27 @@ def get_query_type_int_default(query: int = 10): @app.get("/query/param") -def get_query_param(query=Query(None)): +def get_query_param(query=Query(default=None)): if query is None: return "foo bar" return f"foo bar {query}" @app.get("/query/param-required") -def get_query_param_required(query=Query(...)): +def get_query_param_required(query=Query()): return f"foo bar {query}" @app.get("/query/param-required/int") -def get_query_param_required_type(query: int = Query(...)): +def get_query_param_required_type(query: int = Query()): return f"foo bar {query}" @app.get("/enum-status-code", status_code=http.HTTPStatus.CREATED) def get_enum_status_code(): return "foo bar" + + +@app.get("/query/frozenset") +def get_query_type_frozenset(query: FrozenSet[int] = Query(...)): + return ",".join(map(str, sorted(query))) diff --git a/tests/test_additional_properties.py b/tests/test_additional_properties.py index 9e15e6ed0..016c1f734 100644 --- a/tests/test_additional_properties.py +++ b/tests/test_additional_properties.py @@ -76,7 +76,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_additional_responses_custom_model_in_callback.py b/tests/test_additional_responses_custom_model_in_callback.py index 36dd0d6db..a1072cc56 100644 --- a/tests/test_additional_responses_custom_model_in_callback.py +++ b/tests/test_additional_responses_custom_model_in_callback.py @@ -119,7 +119,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_additional_responses_default_validationerror.py b/tests/test_additional_responses_default_validationerror.py index 6ea372ce8..cabb536d7 100644 --- a/tests/test_additional_responses_default_validationerror.py +++ b/tests/test_additional_responses_default_validationerror.py @@ -54,7 +54,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_application.py b/tests/test_application.py index 5ba737307..b7d72f9ad 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -1090,6 +1090,41 @@ openapi_schema = { "operationId": "get_enum_status_code_enum_status_code_get", } }, + "/query/frozenset": { + "get": { + "summary": "Get Query Type Frozenset", + "operationId": "get_query_type_frozenset_query_frozenset_get", + "parameters": [ + { + "required": True, + "schema": { + "title": "Query", + "uniqueItems": True, + "type": "array", + "items": {"type": "integer"}, + }, + "name": "query", + "in": "query", + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": {"application/json": {"schema": {}}}, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, }, "components": { "schemas": { @@ -1101,7 +1136,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_custom_middleware_exception.py b/tests/test_custom_middleware_exception.py new file mode 100644 index 000000000..d9b81e7c2 --- /dev/null +++ b/tests/test_custom_middleware_exception.py @@ -0,0 +1,95 @@ +from pathlib import Path +from typing import Optional + +from fastapi import APIRouter, FastAPI, File, UploadFile +from fastapi.exceptions import HTTPException +from fastapi.testclient import TestClient + +app = FastAPI() + +router = APIRouter() + + +class ContentSizeLimitMiddleware: + """Content size limiting middleware for ASGI applications + Args: + app (ASGI application): ASGI application + max_content_size (optional): the maximum content size allowed in bytes, None for no limit + """ + + def __init__(self, app: APIRouter, max_content_size: Optional[int] = None): + self.app = app + self.max_content_size = max_content_size + + def receive_wrapper(self, receive): + received = 0 + + async def inner(): + nonlocal received + message = await receive() + if message["type"] != "http.request": + return message # pragma: no cover + + body_len = len(message.get("body", b"")) + received += body_len + if received > self.max_content_size: + raise HTTPException( + 422, + detail={ + "name": "ContentSizeLimitExceeded", + "code": 999, + "message": "File limit exceeded", + }, + ) + return message + + return inner + + async def __call__(self, scope, receive, send): + if scope["type"] != "http" or self.max_content_size is None: + await self.app(scope, receive, send) + return + + wrapper = self.receive_wrapper(receive) + await self.app(scope, wrapper, send) + + +@router.post("/middleware") +def run_middleware(file: UploadFile = File(..., description="Big File")): + return {"message": "OK"} + + +app.include_router(router) +app.add_middleware(ContentSizeLimitMiddleware, max_content_size=2**8) + + +client = TestClient(app) + + +def test_custom_middleware_exception(tmp_path: Path): + default_pydantic_max_size = 2**16 + path = tmp_path / "test.txt" + path.write_bytes(b"x" * (default_pydantic_max_size + 1)) + + with client: + with open(path, "rb") as file: + response = client.post("/middleware", files={"file": file}) + assert response.status_code == 422, response.text + assert response.json() == { + "detail": { + "name": "ContentSizeLimitExceeded", + "code": 999, + "message": "File limit exceeded", + } + } + + +def test_custom_middleware_exception_not_raised(tmp_path: Path): + path = tmp_path / "test.txt" + path.write_bytes(b"") + + with client: + with open(path, "rb") as file: + response = client.post("/middleware", files={"file": file}) + assert response.status_code == 200, response.text + assert response.json() == {"message": "OK"} diff --git a/tests/test_dependency_cache.py b/tests/test_dependency_cache.py index 65ed7f946..08fb9b74f 100644 --- a/tests/test_dependency_cache.py +++ b/tests/test_dependency_cache.py @@ -1,4 +1,4 @@ -from fastapi import Depends, FastAPI +from fastapi import Depends, FastAPI, Security from fastapi.testclient import TestClient app = FastAPI() @@ -35,6 +35,19 @@ async def get_sub_counter_no_cache( return {"counter": count, "subcounter": subcount} +@app.get("/scope-counter") +async def get_scope_counter( + count: int = Security(dep_counter), + scope_count_1: int = Security(dep_counter, scopes=["scope"]), + scope_count_2: int = Security(dep_counter, scopes=["scope"]), +): + return { + "counter": count, + "scope_counter_1": scope_count_1, + "scope_counter_2": scope_count_2, + } + + client = TestClient(app) @@ -66,3 +79,13 @@ def test_sub_counter_no_cache(): response = client.get("/sub-counter-no-cache/") assert response.status_code == 200, response.text assert response.json() == {"counter": 4, "subcounter": 3} + + +def test_security_cache(): + counter_holder["counter"] = 0 + response = client.get("/scope-counter/") + assert response.status_code == 200, response.text + assert response.json() == {"counter": 1, "scope_counter_1": 2, "scope_counter_2": 2} + response = client.get("/scope-counter/") + assert response.status_code == 200, response.text + assert response.json() == {"counter": 3, "scope_counter_1": 4, "scope_counter_2": 4} diff --git a/tests/test_dependency_contextmanager.py b/tests/test_dependency_contextmanager.py index 3e42b47f7..03ef56c4d 100644 --- a/tests/test_dependency_contextmanager.py +++ b/tests/test_dependency_contextmanager.py @@ -235,7 +235,16 @@ def test_sync_raise_other(): assert "/sync_raise" not in errors -def test_async_raise(): +def test_async_raise_raises(): + with pytest.raises(AsyncDependencyError): + client.get("/async_raise") + assert state["/async_raise"] == "asyncgen raise finalized" + assert "/async_raise" in errors + errors.clear() + + +def test_async_raise_server_error(): + client = TestClient(app, raise_server_exceptions=False) response = client.get("/async_raise") assert response.status_code == 500, response.text assert state["/async_raise"] == "asyncgen raise finalized" @@ -270,7 +279,16 @@ def test_background_tasks(): assert state["bg"] == "bg set - b: started b - a: started a" -def test_sync_raise(): +def test_sync_raise_raises(): + with pytest.raises(SyncDependencyError): + client.get("/sync_raise") + assert state["/sync_raise"] == "generator raise finalized" + assert "/sync_raise" in errors + errors.clear() + + +def test_sync_raise_server_error(): + client = TestClient(app, raise_server_exceptions=False) response = client.get("/sync_raise") assert response.status_code == 500, response.text assert state["/sync_raise"] == "generator raise finalized" @@ -306,7 +324,16 @@ def test_sync_sync_raise_other(): assert "/sync_raise" not in errors -def test_sync_async_raise(): +def test_sync_async_raise_raises(): + with pytest.raises(AsyncDependencyError): + client.get("/sync_async_raise") + assert state["/async_raise"] == "asyncgen raise finalized" + assert "/async_raise" in errors + errors.clear() + + +def test_sync_async_raise_server_error(): + client = TestClient(app, raise_server_exceptions=False) response = client.get("/sync_async_raise") assert response.status_code == 500, response.text assert state["/async_raise"] == "asyncgen raise finalized" @@ -314,7 +341,16 @@ def test_sync_async_raise(): errors.clear() -def test_sync_sync_raise(): +def test_sync_sync_raise_raises(): + with pytest.raises(SyncDependencyError): + client.get("/sync_sync_raise") + assert state["/sync_raise"] == "generator raise finalized" + assert "/sync_raise" in errors + errors.clear() + + +def test_sync_sync_raise_server_error(): + client = TestClient(app, raise_server_exceptions=False) response = client.get("/sync_sync_raise") assert response.status_code == 500, response.text assert state["/sync_raise"] == "generator raise finalized" diff --git a/tests/test_dependency_contextvars.py b/tests/test_dependency_contextvars.py new file mode 100644 index 000000000..076802df8 --- /dev/null +++ b/tests/test_dependency_contextvars.py @@ -0,0 +1,51 @@ +from contextvars import ContextVar +from typing import Any, Awaitable, Callable, Dict, Optional + +from fastapi import Depends, FastAPI, Request, Response +from fastapi.testclient import TestClient + +legacy_request_state_context_var: ContextVar[Optional[Dict[str, Any]]] = ContextVar( + "legacy_request_state_context_var", default=None +) + +app = FastAPI() + + +async def set_up_request_state_dependency(): + request_state = {"user": "deadpond"} + contextvar_token = legacy_request_state_context_var.set(request_state) + yield request_state + legacy_request_state_context_var.reset(contextvar_token) + + +@app.middleware("http") +async def custom_middleware( + request: Request, call_next: Callable[[Request], Awaitable[Response]] +): + response = await call_next(request) + response.headers["custom"] = "foo" + return response + + +@app.get("/user", dependencies=[Depends(set_up_request_state_dependency)]) +def get_user(): + request_state = legacy_request_state_context_var.get() + assert request_state + return request_state["user"] + + +client = TestClient(app) + + +def test_dependency_contextvars(): + """ + Check that custom middlewares don't affect the contextvar context for dependencies. + + The code before yield and the code after yield should be run in the same contextvar + context, so that request_state_context_var.reset(contextvar_token). + + If they are run in a different context, that raises an error. + """ + response = client.get("/user") + assert response.json() == "deadpond" + assert response.headers["custom"] == "foo" diff --git a/tests/test_dependency_duplicates.py b/tests/test_dependency_duplicates.py index 5e15812b6..33899134e 100644 --- a/tests/test_dependency_duplicates.py +++ b/tests/test_dependency_duplicates.py @@ -177,7 +177,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_dependency_normal_exceptions.py b/tests/test_dependency_normal_exceptions.py new file mode 100644 index 000000000..23c366d5d --- /dev/null +++ b/tests/test_dependency_normal_exceptions.py @@ -0,0 +1,71 @@ +import pytest +from fastapi import Body, Depends, FastAPI, HTTPException +from fastapi.testclient import TestClient + +initial_fake_database = {"rick": "Rick Sanchez"} + +fake_database = initial_fake_database.copy() + +initial_state = {"except": False, "finally": False} + +state = initial_state.copy() + +app = FastAPI() + + +async def get_database(): + temp_database = fake_database.copy() + try: + yield temp_database + fake_database.update(temp_database) + except HTTPException: + state["except"] = True + finally: + state["finally"] = True + + +@app.put("/invalid-user/{user_id}") +def put_invalid_user( + user_id: str, name: str = Body(), db: dict = Depends(get_database) +): + db[user_id] = name + raise HTTPException(status_code=400, detail="Invalid user") + + +@app.put("/user/{user_id}") +def put_user(user_id: str, name: str = Body(), db: dict = Depends(get_database)): + db[user_id] = name + return {"message": "OK"} + + +@pytest.fixture(autouse=True) +def reset_state_and_db(): + global fake_database + global state + fake_database = initial_fake_database.copy() + state = initial_state.copy() + + +client = TestClient(app) + + +def test_dependency_gets_exception(): + assert state["except"] is False + assert state["finally"] is False + response = client.put("/invalid-user/rick", json="Morty") + assert response.status_code == 400, response.text + assert response.json() == {"detail": "Invalid user"} + assert state["except"] is True + assert state["finally"] is True + assert fake_database["rick"] == "Rick Sanchez" + + +def test_dependency_no_exception(): + assert state["except"] is False + assert state["finally"] is False + response = client.put("/user/rick", json="Morty") + assert response.status_code == 200, response.text + assert response.json() == {"message": "OK"} + assert state["except"] is False + assert state["finally"] is True + assert fake_database["rick"] == "Morty" diff --git a/tests/test_enforce_once_required_parameter.py b/tests/test_enforce_once_required_parameter.py new file mode 100644 index 000000000..ba8c7353f --- /dev/null +++ b/tests/test_enforce_once_required_parameter.py @@ -0,0 +1,111 @@ +from typing import Optional + +from fastapi import Depends, FastAPI, Query, status +from fastapi.testclient import TestClient + +app = FastAPI() + + +def _get_client_key(client_id: str = Query(...)) -> str: + return f"{client_id}_key" + + +def _get_client_tag(client_id: Optional[str] = Query(None)) -> Optional[str]: + if client_id is None: + return None + return f"{client_id}_tag" + + +@app.get("/foo") +def foo_handler( + client_key: str = Depends(_get_client_key), + client_tag: Optional[str] = Depends(_get_client_tag), +): + return {"client_id": client_key, "client_tag": client_tag} + + +client = TestClient(app) + +expected_schema = { + "components": { + "schemas": { + "HTTPValidationError": { + "properties": { + "detail": { + "items": {"$ref": "#/components/schemas/ValidationError"}, + "title": "Detail", + "type": "array", + } + }, + "title": "HTTPValidationError", + "type": "object", + }, + "ValidationError": { + "properties": { + "loc": { + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + "title": "Location", + "type": "array", + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error " "Type", "type": "string"}, + }, + "required": ["loc", "msg", "type"], + "title": "ValidationError", + "type": "object", + }, + } + }, + "info": {"title": "FastAPI", "version": "0.1.0"}, + "openapi": "3.0.2", + "paths": { + "/foo": { + "get": { + "operationId": "foo_handler_foo_get", + "parameters": [ + { + "in": "query", + "name": "client_id", + "required": True, + "schema": {"title": "Client Id", "type": "string"}, + }, + ], + "responses": { + "200": { + "content": {"application/json": {"schema": {}}}, + "description": "Successful " "Response", + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation " "Error", + }, + }, + "summary": "Foo Handler", + } + } + }, +} + + +def test_schema(): + response = client.get("/openapi.json") + assert response.status_code == status.HTTP_200_OK + actual_schema = response.json() + assert actual_schema == expected_schema + + +def test_get_invalid(): + response = client.get("/foo", params={"client_id": None}) + assert response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY + + +def test_get_valid(): + response = client.get("/foo", params={"client_id": "bar"}) + assert response.status_code == 200 + assert response.json() == {"client_id": "bar_key", "client_tag": "bar_tag"} diff --git a/tests/test_exception_handlers.py b/tests/test_exception_handlers.py index 6153f7ab9..67a4becec 100644 --- a/tests/test_exception_handlers.py +++ b/tests/test_exception_handlers.py @@ -1,3 +1,4 @@ +import pytest from fastapi import FastAPI, HTTPException from fastapi.exceptions import RequestValidationError from fastapi.testclient import TestClient @@ -12,10 +13,15 @@ def request_validation_exception_handler(request, exception): return JSONResponse({"exception": "request-validation"}) +def server_error_exception_handler(request, exception): + return JSONResponse(status_code=500, content={"exception": "server-error"}) + + app = FastAPI( exception_handlers={ HTTPException: http_exception_handler, RequestValidationError: request_validation_exception_handler, + Exception: server_error_exception_handler, } ) @@ -32,6 +38,11 @@ def route_with_request_validation_exception(param: int): pass # pragma: no cover +@app.get("/server-error") +def route_with_server_error(): + raise RuntimeError("Oops!") + + def test_override_http_exception(): response = client.get("/http-exception") assert response.status_code == 200 @@ -42,3 +53,15 @@ def test_override_request_validation_exception(): response = client.get("/request-validation/invalid") assert response.status_code == 200 assert response.json() == {"exception": "request-validation"} + + +def test_override_server_error_exception_raises(): + with pytest.raises(RuntimeError): + client.get("/server-error") + + +def test_override_server_error_exception_response(): + client = TestClient(app, raise_server_exceptions=False) + response = client.get("/server-error") + assert response.status_code == 500 + assert response.json() == {"exception": "server-error"} diff --git a/tests/test_extra_routes.py b/tests/test_extra_routes.py index 6aba3e8dd..491ba61c6 100644 --- a/tests/test_extra_routes.py +++ b/tests/test_extra_routes.py @@ -32,12 +32,12 @@ def delete_item(item_id: str, item: Item): @app.head("/items/{item_id}") def head_item(item_id: str): - return JSONResponse(headers={"x-fastapi-item-id": item_id}) + return JSONResponse(None, headers={"x-fastapi-item-id": item_id}) @app.options("/items/{item_id}") def options_item(item_id: str): - return JSONResponse(headers={"x-fastapi-item-id": item_id}) + return JSONResponse(None, headers={"x-fastapi-item-id": item_id}) @app.patch("/items/{item_id}") @@ -47,7 +47,7 @@ def patch_item(item_id: str, item: Item): @app.trace("/items/{item_id}") def trace_item(item_id: str): - return JSONResponse(media_type="message/http") + return JSONResponse(None, media_type="message/http") client = TestClient(app) @@ -292,7 +292,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_filter_pydantic_sub_model.py b/tests/test_filter_pydantic_sub_model.py index 90a372976..8814356a1 100644 --- a/tests/test_filter_pydantic_sub_model.py +++ b/tests/test_filter_pydantic_sub_model.py @@ -116,7 +116,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_forms_from_non_typing_sequences.py b/tests/test_forms_from_non_typing_sequences.py index be917eab7..52ce24753 100644 --- a/tests/test_forms_from_non_typing_sequences.py +++ b/tests/test_forms_from_non_typing_sequences.py @@ -5,17 +5,17 @@ app = FastAPI() @app.post("/form/python-list") -def post_form_param_list(items: list = Form(...)): +def post_form_param_list(items: list = Form()): return items @app.post("/form/python-set") -def post_form_param_set(items: set = Form(...)): +def post_form_param_set(items: set = Form()): return items @app.post("/form/python-tuple") -def post_form_param_tuple(items: tuple = Form(...)): +def post_form_param_tuple(items: tuple = Form()): return items diff --git a/tests/test_generate_unique_id_function.py b/tests/test_generate_unique_id_function.py new file mode 100644 index 000000000..0b519f859 --- /dev/null +++ b/tests/test_generate_unique_id_function.py @@ -0,0 +1,1631 @@ +import warnings +from typing import List + +from fastapi import APIRouter, FastAPI +from fastapi.routing import APIRoute +from fastapi.testclient import TestClient +from pydantic import BaseModel + + +def custom_generate_unique_id(route: APIRoute): + return f"foo_{route.name}" + + +def custom_generate_unique_id2(route: APIRoute): + return f"bar_{route.name}" + + +def custom_generate_unique_id3(route: APIRoute): + return f"baz_{route.name}" + + +class Item(BaseModel): + name: str + price: float + + +class Message(BaseModel): + title: str + description: str + + +def test_top_level_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter() + + @app.post("/", response_model=List[Item], responses={404: {"model": List[Message]}}) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", response_model=List[Item], responses={404: {"model": List[Message]}} + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + app.include_router(router) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "foo_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "foo_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_foo_post_root": { + "title": "Body_foo_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_router": { + "title": "Body_foo_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_router_overrides_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @app.post("/", response_model=List[Item], responses={404: {"model": List[Message]}}) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", response_model=List[Item], responses={404: {"model": List[Message]}} + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + app.include_router(router) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "foo_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "bar_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_bar_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Bar Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Bar Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_bar_post_router": { + "title": "Body_bar_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_root": { + "title": "Body_foo_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_router_include_overrides_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @app.post("/", response_model=List[Item], responses={404: {"model": List[Message]}}) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", response_model=List[Item], responses={404: {"model": List[Message]}} + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + app.include_router(router, generate_unique_id_function=custom_generate_unique_id3) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "foo_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "bar_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_bar_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Bar Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Bar Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_bar_post_router": { + "title": "Body_bar_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_root": { + "title": "Body_foo_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_subrouter_top_level_include_overrides_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter() + sub_router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @app.post("/", response_model=List[Item], responses={404: {"model": List[Message]}}) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", response_model=List[Item], responses={404: {"model": List[Message]}} + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @sub_router.post( + "/subrouter", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + ) + def post_subrouter(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + router.include_router(sub_router) + app.include_router(router, generate_unique_id_function=custom_generate_unique_id3) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "foo_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "baz_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_baz_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Baz Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Baz Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/subrouter": { + "post": { + "summary": "Post Subrouter", + "operationId": "bar_post_subrouter", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_bar_post_subrouter" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Bar Post Subrouter", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Bar Post Subrouter", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_bar_post_subrouter": { + "title": "Body_bar_post_subrouter", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_baz_post_router": { + "title": "Body_baz_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_root": { + "title": "Body_foo_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_router_path_operation_overrides_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @app.post("/", response_model=List[Item], responses={404: {"model": List[Message]}}) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + generate_unique_id_function=custom_generate_unique_id3, + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + app.include_router(router) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "foo_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "baz_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_baz_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Baz Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Baz Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_baz_post_router": { + "title": "Body_baz_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_root": { + "title": "Body_foo_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_app_path_operation_overrides_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @app.post( + "/", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + generate_unique_id_function=custom_generate_unique_id3, + ) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @router.post( + "/router", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + ) + def post_router(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + app.include_router(router) + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "baz_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_baz_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Baz Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Baz Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + "/router": { + "post": { + "summary": "Post Router", + "operationId": "bar_post_router", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_bar_post_router" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Bar Post Router", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Bar Post Router", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_bar_post_router": { + "title": "Body_bar_post_router", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_baz_post_root": { + "title": "Body_baz_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_callback_override_generate_unique_id(): + app = FastAPI(generate_unique_id_function=custom_generate_unique_id) + callback_router = APIRouter(generate_unique_id_function=custom_generate_unique_id2) + + @callback_router.post( + "/post-callback", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + generate_unique_id_function=custom_generate_unique_id3, + ) + def post_callback(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @app.post( + "/", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + generate_unique_id_function=custom_generate_unique_id3, + callbacks=callback_router.routes, + ) + def post_root(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + @app.post( + "/tocallback", + response_model=List[Item], + responses={404: {"model": List[Message]}}, + ) + def post_with_callback(item1: Item, item2: Item): + return item1, item2 # pragma: nocover + + client = TestClient(app) + response = client.get("/openapi.json") + data = response.json() + assert data == { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "post": { + "summary": "Post Root", + "operationId": "baz_post_root", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_baz_post_root" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Baz Post Root", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Baz Post Root", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + "callbacks": { + "post_callback": { + "/post-callback": { + "post": { + "summary": "Post Callback", + "operationId": "baz_post_callback", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_baz_post_callback" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Baz Post Callback", + "type": "array", + "items": { + "$ref": "#/components/schemas/Item" + }, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Baz Post Callback", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + } + } + }, + } + }, + "/tocallback": { + "post": { + "summary": "Post With Callback", + "operationId": "foo_post_with_callback", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_foo_post_with_callback" + } + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Foo Post With Callback", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "title": "Response 404 Foo Post With Callback", + "type": "array", + "items": { + "$ref": "#/components/schemas/Message" + }, + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "Body_baz_post_callback": { + "title": "Body_baz_post_callback", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_baz_post_root": { + "title": "Body_baz_post_root", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "Body_foo_post_with_callback": { + "title": "Body_foo_post_with_callback", + "required": ["item1", "item2"], + "type": "object", + "properties": { + "item1": {"$ref": "#/components/schemas/Item"}, + "item2": {"$ref": "#/components/schemas/Item"}, + }, + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "Message": { + "title": "Message", + "required": ["title", "description"], + "type": "object", + "properties": { + "title": {"title": "Title", "type": "string"}, + "description": {"title": "Description", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "anyOf": [{"type": "string"}, {"type": "integer"}] + }, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, + } + + +def test_warn_duplicate_operation_id(): + def broken_operation_id(route: APIRoute): + return "foo" + + app = FastAPI(generate_unique_id_function=broken_operation_id) + + @app.post("/") + def post_root(item1: Item): + return item1 # pragma: nocover + + @app.post("/second") + def post_second(item1: Item): + return item1 # pragma: nocover + + @app.post("/third") + def post_third(item1: Item): + return item1 # pragma: nocover + + client = TestClient(app) + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter("always") + client.get("/openapi.json") + assert len(w) == 2 + assert issubclass(w[-1].category, UserWarning) + assert "Duplicate Operation ID" in str(w[-1].message) diff --git a/tests/test_get_request_body.py b/tests/test_get_request_body.py index b12f499eb..88b9d839f 100644 --- a/tests/test_get_request_body.py +++ b/tests/test_get_request_body.py @@ -85,7 +85,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_include_router_defaults_overrides.py b/tests/test_include_router_defaults_overrides.py index c46cb6701..ccb6c7229 100644 --- a/tests/test_include_router_defaults_overrides.py +++ b/tests/test_include_router_defaults_overrides.py @@ -1,3 +1,5 @@ +import warnings + import pytest from fastapi import APIRouter, Depends, FastAPI, Response from fastapi.responses import JSONResponse @@ -343,7 +345,11 @@ client = TestClient(app) def test_openapi(): client = TestClient(app) - response = client.get("/openapi.json") + with warnings.catch_warnings(record=True) as w: + warnings.simplefilter("always") + response = client.get("/openapi.json") + assert issubclass(w[-1].category, UserWarning) + assert "Duplicate Operation ID" in str(w[-1].message) assert response.json() == openapi_schema @@ -6606,7 +6612,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_invalid_sequence_param.py b/tests/test_invalid_sequence_param.py index f00dd7b93..475786adb 100644 --- a/tests/test_invalid_sequence_param.py +++ b/tests/test_invalid_sequence_param.py @@ -13,7 +13,7 @@ def test_invalid_sequence(): title: str @app.get("/items/") - def read_items(q: List[Item] = Query(None)): + def read_items(q: List[Item] = Query(default=None)): pass # pragma: no cover @@ -25,7 +25,7 @@ def test_invalid_tuple(): title: str @app.get("/items/") - def read_items(q: Tuple[Item, Item] = Query(None)): + def read_items(q: Tuple[Item, Item] = Query(default=None)): pass # pragma: no cover @@ -37,7 +37,7 @@ def test_invalid_dict(): title: str @app.get("/items/") - def read_items(q: Dict[str, Item] = Query(None)): + def read_items(q: Dict[str, Item] = Query(default=None)): pass # pragma: no cover @@ -49,5 +49,5 @@ def test_invalid_simple_dict(): title: str @app.get("/items/") - def read_items(q: Optional[dict] = Query(None)): + def read_items(q: Optional[dict] = Query(default=None)): pass # pragma: no cover diff --git a/tests/test_jsonable_encoder.py b/tests/test_jsonable_encoder.py index fa82b5ea8..f4fdcf601 100644 --- a/tests/test_jsonable_encoder.py +++ b/tests/test_jsonable_encoder.py @@ -1,3 +1,4 @@ +from dataclasses import dataclass from datetime import datetime, timezone from enum import Enum from pathlib import PurePath, PurePosixPath, PureWindowsPath @@ -19,6 +20,12 @@ class Pet: self.name = name +@dataclass +class Item: + name: str + count: int + + class DictablePerson(Person): def __iter__(self): return ((k, v) for k, v in self.__dict__.items()) @@ -67,7 +74,7 @@ class ModelWithConfig(BaseModel): class ModelWithAlias(BaseModel): - foo: str = Field(..., alias="Foo") + foo: str = Field(alias="Foo") class ModelWithDefault(BaseModel): @@ -93,16 +100,51 @@ def fixture_model_with_path(request): return ModelWithPath(path=request.param("/foo", "bar")) +def test_encode_dict(): + pet = {"name": "Firulais", "owner": {"name": "Foo"}} + assert jsonable_encoder(pet) == {"name": "Firulais", "owner": {"name": "Foo"}} + assert jsonable_encoder(pet, include={"name"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, exclude={"owner"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, include={}) == {} + assert jsonable_encoder(pet, exclude={}) == { + "name": "Firulais", + "owner": {"name": "Foo"}, + } + + def test_encode_class(): person = Person(name="Foo") pet = Pet(owner=person, name="Firulais") assert jsonable_encoder(pet) == {"name": "Firulais", "owner": {"name": "Foo"}} + assert jsonable_encoder(pet, include={"name"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, exclude={"owner"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, include={}) == {} + assert jsonable_encoder(pet, exclude={}) == { + "name": "Firulais", + "owner": {"name": "Foo"}, + } def test_encode_dictable(): person = DictablePerson(name="Foo") pet = DictablePet(owner=person, name="Firulais") assert jsonable_encoder(pet) == {"name": "Firulais", "owner": {"name": "Foo"}} + assert jsonable_encoder(pet, include={"name"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, exclude={"owner"}) == {"name": "Firulais"} + assert jsonable_encoder(pet, include={}) == {} + assert jsonable_encoder(pet, exclude={}) == { + "name": "Firulais", + "owner": {"name": "Foo"}, + } + + +def test_encode_dataclass(): + item = Item(name="foo", count=100) + assert jsonable_encoder(item) == {"name": "foo", "count": 100} + assert jsonable_encoder(item, include={"name"}) == {"name": "foo"} + assert jsonable_encoder(item, exclude={"count"}) == {"name": "foo"} + assert jsonable_encoder(item, include={}) == {} + assert jsonable_encoder(item, exclude={}) == {"name": "foo", "count": 100} def test_encode_unsupported(): @@ -144,6 +186,14 @@ def test_encode_model_with_default(): assert jsonable_encoder(model, exclude_unset=True, exclude_defaults=True) == { "foo": "foo" } + assert jsonable_encoder(model, include={"foo"}) == {"foo": "foo"} + assert jsonable_encoder(model, exclude={"bla"}) == {"foo": "foo", "bar": "bar"} + assert jsonable_encoder(model, include={}) == {} + assert jsonable_encoder(model, exclude={}) == { + "foo": "foo", + "bar": "bar", + "bla": "bla", + } def test_custom_encoders(): diff --git a/tests/test_modules_same_name_body/app/a.py b/tests/test_modules_same_name_body/app/a.py index 3c86c1865..377236890 100644 --- a/tests/test_modules_same_name_body/app/a.py +++ b/tests/test_modules_same_name_body/app/a.py @@ -4,5 +4,5 @@ router = APIRouter() @router.post("/compute") -def compute(a: int = Body(...), b: str = Body(...)): +def compute(a: int = Body(), b: str = Body()): return {"a": a, "b": b} diff --git a/tests/test_modules_same_name_body/app/b.py b/tests/test_modules_same_name_body/app/b.py index f7c7fdfc6..b62118f84 100644 --- a/tests/test_modules_same_name_body/app/b.py +++ b/tests/test_modules_same_name_body/app/b.py @@ -4,5 +4,5 @@ router = APIRouter() @router.post("/compute/") -def compute(a: int = Body(...), b: str = Body(...)): +def compute(a: int = Body(), b: str = Body()): return {"a": a, "b": b} diff --git a/tests/test_modules_same_name_body/test_main.py b/tests/test_modules_same_name_body/test_main.py index b0d3330c7..8b1aea031 100644 --- a/tests/test_modules_same_name_body/test_main.py +++ b/tests/test_modules_same_name_body/test_main.py @@ -101,7 +101,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_multi_body_errors.py b/tests/test_multi_body_errors.py index c1be82806..31308ea85 100644 --- a/tests/test_multi_body_errors.py +++ b/tests/test_multi_body_errors.py @@ -79,7 +79,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_multi_query_errors.py b/tests/test_multi_query_errors.py index 69ea87a9b..3da461af5 100644 --- a/tests/test_multi_query_errors.py +++ b/tests/test_multi_query_errors.py @@ -7,7 +7,7 @@ app = FastAPI() @app.get("/items/") -def read_items(q: List[int] = Query(None)): +def read_items(q: List[int] = Query(default=None)): return {"q": q} @@ -63,7 +63,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_multipart_installation.py b/tests/test_multipart_installation.py index c8a6fd942..788d9ef5a 100644 --- a/tests/test_multipart_installation.py +++ b/tests/test_multipart_installation.py @@ -12,7 +12,7 @@ def test_incorrect_multipart_installed_form(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...)): + async def root(username: str = Form()): return username # pragma: nocover @@ -22,7 +22,7 @@ def test_incorrect_multipart_installed_file_upload(monkeypatch): app = FastAPI() @app.post("/") - async def root(f: UploadFile = File(...)): + async def root(f: UploadFile = File()): return f # pragma: nocover @@ -32,7 +32,7 @@ def test_incorrect_multipart_installed_file_bytes(monkeypatch): app = FastAPI() @app.post("/") - async def root(f: bytes = File(...)): + async def root(f: bytes = File()): return f # pragma: nocover @@ -42,7 +42,7 @@ def test_incorrect_multipart_installed_multi_form(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...), password: str = Form(...)): + async def root(username: str = Form(), password: str = Form()): return username # pragma: nocover @@ -52,7 +52,7 @@ def test_incorrect_multipart_installed_form_file(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...), f: UploadFile = File(...)): + async def root(username: str = Form(), f: UploadFile = File()): return username # pragma: nocover @@ -62,7 +62,7 @@ def test_no_multipart_installed(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...)): + async def root(username: str = Form()): return username # pragma: nocover @@ -72,7 +72,7 @@ def test_no_multipart_installed_file(monkeypatch): app = FastAPI() @app.post("/") - async def root(f: UploadFile = File(...)): + async def root(f: UploadFile = File()): return f # pragma: nocover @@ -82,7 +82,7 @@ def test_no_multipart_installed_file_bytes(monkeypatch): app = FastAPI() @app.post("/") - async def root(f: bytes = File(...)): + async def root(f: bytes = File()): return f # pragma: nocover @@ -92,7 +92,7 @@ def test_no_multipart_installed_multi_form(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...), password: str = Form(...)): + async def root(username: str = Form(), password: str = Form()): return username # pragma: nocover @@ -102,5 +102,5 @@ def test_no_multipart_installed_form_file(monkeypatch): app = FastAPI() @app.post("/") - async def root(username: str = Form(...), f: UploadFile = File(...)): + async def root(username: str = Form(), f: UploadFile = File()): return username # pragma: nocover diff --git a/tests/test_openapi_query_parameter_extension.py b/tests/test_openapi_query_parameter_extension.py new file mode 100644 index 000000000..d3996f26e --- /dev/null +++ b/tests/test_openapi_query_parameter_extension.py @@ -0,0 +1,127 @@ +from typing import Optional + +from fastapi import FastAPI +from fastapi.testclient import TestClient + +app = FastAPI() + + +@app.get( + "/", + openapi_extra={ + "parameters": [ + { + "required": False, + "schema": {"title": "Extra Param 1"}, + "name": "extra_param_1", + "in": "query", + }, + { + "required": True, + "schema": {"title": "Extra Param 2"}, + "name": "extra_param_2", + "in": "query", + }, + ] + }, +) +def route_with_extra_query_parameters(standard_query_param: Optional[int] = 50): + return {} + + +client = TestClient(app) + + +openapi_schema = { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/": { + "get": { + "summary": "Route With Extra Query Parameters", + "operationId": "route_with_extra_query_parameters__get", + "parameters": [ + { + "required": False, + "schema": { + "title": "Standard Query Param", + "type": "integer", + "default": 50, + }, + "name": "standard_query_param", + "in": "query", + }, + { + "required": False, + "schema": {"title": "Extra Param 1"}, + "name": "extra_param_1", + "in": "query", + }, + { + "required": True, + "schema": {"title": "Extra Param 2"}, + "name": "extra_param_2", + "in": "query", + }, + ], + "responses": { + "200": { + "description": "Successful Response", + "content": {"application/json": {"schema": {}}}, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + } + }, + "components": { + "schemas": { + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, +} + + +def test_openapi(): + response = client.get("/openapi.json") + assert response.status_code == 200, response.text + assert response.json() == openapi_schema + + +def test_get_route(): + response = client.get("/") + assert response.status_code == 200, response.text + assert response.json() == {} diff --git a/tests/test_orjson_response_class.py b/tests/test_orjson_response_class.py new file mode 100644 index 000000000..6fe62daf9 --- /dev/null +++ b/tests/test_orjson_response_class.py @@ -0,0 +1,21 @@ +from fastapi import FastAPI +from fastapi.responses import ORJSONResponse +from fastapi.testclient import TestClient +from sqlalchemy.sql.elements import quoted_name + +app = FastAPI(default_response_class=ORJSONResponse) + + +@app.get("/orjson_non_str_keys") +def get_orjson_non_str_keys(): + key = quoted_name(value="msg", quote=False) + return {key: "Hello World", 1: 1} + + +client = TestClient(app) + + +def test_orjson_non_str_keys(): + with client: + response = client.get("/orjson_non_str_keys") + assert response.json() == {"msg": "Hello World", "1": 1} diff --git a/tests/test_param_class.py b/tests/test_param_class.py index f5767ec96..1fd40dcd2 100644 --- a/tests/test_param_class.py +++ b/tests/test_param_class.py @@ -8,7 +8,7 @@ app = FastAPI() @app.get("/items/") -def read_items(q: Optional[str] = Param(None)): # type: ignore +def read_items(q: Optional[str] = Param(default=None)): # type: ignore return {"q": q} diff --git a/tests/test_param_in_path_and_dependency.py b/tests/test_param_in_path_and_dependency.py index 0a94c2151..4d85afbce 100644 --- a/tests/test_param_in_path_and_dependency.py +++ b/tests/test_param_in_path_and_dependency.py @@ -71,7 +71,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_param_include_in_schema.py b/tests/test_param_include_in_schema.py index 4eaac72d8..214f039b6 100644 --- a/tests/test_param_include_in_schema.py +++ b/tests/test_param_include_in_schema.py @@ -9,26 +9,26 @@ app = FastAPI() @app.get("/hidden_cookie") async def hidden_cookie( - hidden_cookie: Optional[str] = Cookie(None, include_in_schema=False) + hidden_cookie: Optional[str] = Cookie(default=None, include_in_schema=False) ): return {"hidden_cookie": hidden_cookie} @app.get("/hidden_header") async def hidden_header( - hidden_header: Optional[str] = Header(None, include_in_schema=False) + hidden_header: Optional[str] = Header(default=None, include_in_schema=False) ): return {"hidden_header": hidden_header} @app.get("/hidden_path/{hidden_path}") -async def hidden_path(hidden_path: str = Path(..., include_in_schema=False)): +async def hidden_path(hidden_path: str = Path(include_in_schema=False)): return {"hidden_path": hidden_path} @app.get("/hidden_query") async def hidden_query( - hidden_query: Optional[str] = Query(None, include_in_schema=False) + hidden_query: Optional[str] = Query(default=None, include_in_schema=False) ): return {"hidden_query": hidden_query} @@ -149,7 +149,7 @@ openapi_shema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_put_no_body.py b/tests/test_put_no_body.py index 1c2cfac89..3da294ccf 100644 --- a/tests/test_put_no_body.py +++ b/tests/test_put_no_body.py @@ -57,7 +57,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_query.py b/tests/test_query.py index cdbdd1ccd..0c73eb665 100644 --- a/tests/test_query.py +++ b/tests/test_query.py @@ -53,6 +53,7 @@ response_not_valid_int = { ("/query/param-required/int", 422, response_missing), ("/query/param-required/int?query=50", 200, "foo bar 50"), ("/query/param-required/int?query=foo", 422, response_not_valid_int), + ("/query/frozenset/?query=1&query=1&query=2", 200, "1,2"), ], ) def test_get_path(path, expected_status, expected_response): diff --git a/tests/test_repeated_dependency_schema.py b/tests/test_repeated_dependency_schema.py index fd616e12a..ca0305184 100644 --- a/tests/test_repeated_dependency_schema.py +++ b/tests/test_repeated_dependency_schema.py @@ -4,7 +4,7 @@ from fastapi.testclient import TestClient app = FastAPI() -def get_header(*, someheader: str = Header(...)): +def get_header(*, someheader: str = Header()): return someheader @@ -36,7 +36,7 @@ schema = { "ValidationError": { "properties": { "loc": { - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, "title": "Location", "type": "array", }, diff --git a/tests/test_repeated_parameter_alias.py b/tests/test_repeated_parameter_alias.py new file mode 100644 index 000000000..823f53a95 --- /dev/null +++ b/tests/test_repeated_parameter_alias.py @@ -0,0 +1,100 @@ +from fastapi import FastAPI, Path, Query, status +from fastapi.testclient import TestClient + +app = FastAPI() + + +@app.get("/{repeated_alias}") +def get_parameters_with_repeated_aliases( + path: str = Path(..., alias="repeated_alias"), + query: str = Query(..., alias="repeated_alias"), +): + return {"path": path, "query": query} + + +client = TestClient(app) + +openapi_schema = { + "components": { + "schemas": { + "HTTPValidationError": { + "properties": { + "detail": { + "items": {"$ref": "#/components/schemas/ValidationError"}, + "title": "Detail", + "type": "array", + } + }, + "title": "HTTPValidationError", + "type": "object", + }, + "ValidationError": { + "properties": { + "loc": { + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + "title": "Location", + "type": "array", + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + "required": ["loc", "msg", "type"], + "title": "ValidationError", + "type": "object", + }, + } + }, + "info": {"title": "FastAPI", "version": "0.1.0"}, + "openapi": "3.0.2", + "paths": { + "/{repeated_alias}": { + "get": { + "operationId": "get_parameters_with_repeated_aliases__repeated_alias__get", + "parameters": [ + { + "in": "path", + "name": "repeated_alias", + "required": True, + "schema": {"title": "Repeated Alias", "type": "string"}, + }, + { + "in": "query", + "name": "repeated_alias", + "required": True, + "schema": {"title": "Repeated Alias", "type": "string"}, + }, + ], + "responses": { + "200": { + "content": {"application/json": {"schema": {}}}, + "description": "Successful Response", + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error", + }, + }, + "summary": "Get Parameters With Repeated Aliases", + } + } + }, +} + + +def test_openapi_schema(): + response = client.get("/openapi.json") + assert response.status_code == status.HTTP_200_OK + actual_schema = response.json() + assert actual_schema == openapi_schema + + +def test_get_parameters(): + response = client.get("/test_path", params={"repeated_alias": "test_query"}) + assert response.status_code == 200, response.text + assert response.json() == {"path": "test_path", "query": "test_query"} diff --git a/tests/test_reponse_set_reponse_code_empty.py b/tests/test_reponse_set_reponse_code_empty.py new file mode 100644 index 000000000..094d54a84 --- /dev/null +++ b/tests/test_reponse_set_reponse_code_empty.py @@ -0,0 +1,97 @@ +from typing import Any + +from fastapi import FastAPI, Response +from fastapi.testclient import TestClient + +app = FastAPI() + + +@app.delete( + "/{id}", + status_code=204, +) +async def delete_deployment( + id: int, + response: Response, +) -> Any: + response.status_code = 400 + return {"msg": "Status overwritten", "id": id} + + +client = TestClient(app) + + +openapi_schema = { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/{id}": { + "delete": { + "summary": "Delete Deployment", + "operationId": "delete_deployment__id__delete", + "parameters": [ + { + "required": True, + "schema": {"title": "Id", "type": "integer"}, + "name": "id", + "in": "path", + } + ], + "responses": { + "204": {"description": "Successful Response"}, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + } + }, + "components": { + "schemas": { + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, +} + + +def test_openapi_schema(): + response = client.get("/openapi.json") + assert response.status_code == 200, response.text + assert response.json() == openapi_schema + + +def test_dependency_set_status_code(): + response = client.delete("/1") + assert response.status_code == 400 and response.content + assert response.json() == {"msg": "Status overwritten", "id": 1} diff --git a/tests/test_request_body_parameters_media_type.py b/tests/test_request_body_parameters_media_type.py index ace6bdef7..e9cf4006d 100644 --- a/tests/test_request_body_parameters_media_type.py +++ b/tests/test_request_body_parameters_media_type.py @@ -21,14 +21,14 @@ class Shop(BaseModel): @app.post("/products") -async def create_product(data: Product = Body(..., media_type=media_type, embed=True)): +async def create_product(data: Product = Body(media_type=media_type, embed=True)): pass # pragma: no cover @app.post("/shops") async def create_shop( - data: Shop = Body(..., media_type=media_type), - included: typing.List[Product] = Body([], media_type=media_type), + data: Shop = Body(media_type=media_type), + included: typing.List[Product] = Body(default=[], media_type=media_type), ): pass # pragma: no cover diff --git a/tests/test_required_noneable.py b/tests/test_required_noneable.py new file mode 100644 index 000000000..5da8cd4d0 --- /dev/null +++ b/tests/test_required_noneable.py @@ -0,0 +1,62 @@ +from typing import Union + +from fastapi import Body, FastAPI, Query +from fastapi.testclient import TestClient + +app = FastAPI() + + +@app.get("/query") +def read_query(q: Union[str, None]): + return q + + +@app.get("/explicit-query") +def read_explicit_query(q: Union[str, None] = Query()): + return q + + +@app.post("/body-embed") +def send_body_embed(b: Union[str, None] = Body(embed=True)): + return b + + +client = TestClient(app) + + +def test_required_nonable_query_invalid(): + response = client.get("/query") + assert response.status_code == 422 + + +def test_required_noneable_query_value(): + response = client.get("/query", params={"q": "foo"}) + assert response.status_code == 200 + assert response.json() == "foo" + + +def test_required_nonable_explicit_query_invalid(): + response = client.get("/explicit-query") + assert response.status_code == 422 + + +def test_required_nonable_explicit_query_value(): + response = client.get("/explicit-query", params={"q": "foo"}) + assert response.status_code == 200 + assert response.json() == "foo" + + +def test_required_nonable_body_embed_no_content(): + response = client.post("/body-embed") + assert response.status_code == 422 + + +def test_required_nonable_body_embed_invalid(): + response = client.post("/body-embed", json={"invalid": "invalid"}) + assert response.status_code == 422 + + +def test_required_noneable_body_embed_value(): + response = client.post("/body-embed", json={"b": "foo"}) + assert response.status_code == 200 + assert response.json() == "foo" diff --git a/tests/test_response_code_no_body.py b/tests/test_response_code_no_body.py index 45e2fabc7..6d9b5c333 100644 --- a/tests/test_response_code_no_body.py +++ b/tests/test_response_code_no_body.py @@ -28,7 +28,7 @@ class JsonApiError(BaseModel): responses={500: {"description": "Error", "model": JsonApiError}}, ) async def a(): - pass # pragma: no cover + pass @app.get("/b", responses={204: {"description": "No Content"}}) @@ -106,3 +106,10 @@ def test_openapi_schema(): response = client.get("/openapi.json") assert response.status_code == 200, response.text assert response.json() == openapi_schema + + +def test_get_response(): + response = client.get("/a") + assert response.status_code == 204, response.text + assert "content-length" not in response.headers + assert response.content == b"" diff --git a/tests/test_route_scope.py b/tests/test_route_scope.py new file mode 100644 index 000000000..a188e9a5f --- /dev/null +++ b/tests/test_route_scope.py @@ -0,0 +1,50 @@ +import pytest +from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect +from fastapi.routing import APIRoute, APIWebSocketRoute +from fastapi.testclient import TestClient + +app = FastAPI() + + +@app.get("/users/{user_id}") +async def get_user(user_id: str, request: Request): + route: APIRoute = request.scope["route"] + return {"user_id": user_id, "path": route.path} + + +@app.websocket("/items/{item_id}") +async def websocket_item(item_id: str, websocket: WebSocket): + route: APIWebSocketRoute = websocket.scope["route"] + await websocket.accept() + await websocket.send_json({"item_id": item_id, "path": route.path}) + + +client = TestClient(app) + + +def test_get(): + response = client.get("/users/rick") + assert response.status_code == 200, response.text + assert response.json() == {"user_id": "rick", "path": "/users/{user_id}"} + + +def test_invalid_method_doesnt_match(): + response = client.post("/users/rick") + assert response.status_code == 405, response.text + + +def test_invalid_path_doesnt_match(): + response = client.post("/usersx/rick") + assert response.status_code == 404, response.text + + +def test_websocket(): + with client.websocket_connect("/items/portal-gun") as websocket: + data = websocket.receive_json() + assert data == {"item_id": "portal-gun", "path": "/items/{item_id}"} + + +def test_websocket_invalid_path_doesnt_match(): + with pytest.raises(WebSocketDisconnect): + with client.websocket_connect("/itemsx/portal-gun") as websocket: + websocket.receive_json() diff --git a/tests/test_schema_extra_examples.py b/tests/test_schema_extra_examples.py index 3e0d846cd..f07d2c3b8 100644 --- a/tests/test_schema_extra_examples.py +++ b/tests/test_schema_extra_examples.py @@ -1,3 +1,5 @@ +from typing import Union + from fastapi import Body, Cookie, FastAPI, Header, Path, Query from fastapi.testclient import TestClient from pydantic import BaseModel @@ -18,14 +20,13 @@ def schema_extra(item: Item): @app.post("/example/") -def example(item: Item = Body(..., example={"data": "Data in Body example"})): +def example(item: Item = Body(example={"data": "Data in Body example"})): return item @app.post("/examples/") def examples( item: Item = Body( - ..., examples={ "example1": { "summary": "example1 summary", @@ -41,7 +42,6 @@ def examples( @app.post("/example_examples/") def example_examples( item: Item = Body( - ..., example={"data": "Overriden example"}, examples={ "example1": {"value": {"data": "examples example_examples 1"}}, @@ -55,7 +55,7 @@ def example_examples( # TODO: enable these tests once/if Form(embed=False) is supported # TODO: In that case, define if File() should support example/examples too # @app.post("/form_example") -# def form_example(firstname: str = Form(..., example="John")): +# def form_example(firstname: str = Form(example="John")): # return firstname @@ -89,7 +89,6 @@ def example_examples( @app.get("/path_example/{item_id}") def path_example( item_id: str = Path( - ..., example="item_1", ), ): @@ -99,7 +98,6 @@ def path_example( @app.get("/path_examples/{item_id}") def path_examples( item_id: str = Path( - ..., examples={ "example1": {"summary": "item ID summary", "value": "item_1"}, "example2": {"value": "item_2"}, @@ -112,7 +110,6 @@ def path_examples( @app.get("/path_example_examples/{item_id}") def path_example_examples( item_id: str = Path( - ..., example="item_overriden", examples={ "example1": {"summary": "item ID summary", "value": "item_1"}, @@ -125,8 +122,8 @@ def path_example_examples( @app.get("/query_example/") def query_example( - data: str = Query( - None, + data: Union[str, None] = Query( + default=None, example="query1", ), ): @@ -135,8 +132,8 @@ def query_example( @app.get("/query_examples/") def query_examples( - data: str = Query( - None, + data: Union[str, None] = Query( + default=None, examples={ "example1": {"summary": "Query example 1", "value": "query1"}, "example2": {"value": "query2"}, @@ -148,11 +145,11 @@ def query_examples( @app.get("/query_example_examples/") def query_example_examples( - data: str = Query( - None, + data: Union[str, None] = Query( + default=None, example="query_overriden", examples={ - "example1": {"summary": "Qeury example 1", "value": "query1"}, + "example1": {"summary": "Query example 1", "value": "query1"}, "example2": {"value": "query2"}, }, ), @@ -162,8 +159,8 @@ def query_example_examples( @app.get("/header_example/") def header_example( - data: str = Header( - None, + data: Union[str, None] = Header( + default=None, example="header1", ), ): @@ -172,8 +169,8 @@ def header_example( @app.get("/header_examples/") def header_examples( - data: str = Header( - None, + data: Union[str, None] = Header( + default=None, examples={ "example1": {"summary": "header example 1", "value": "header1"}, "example2": {"value": "header2"}, @@ -185,11 +182,11 @@ def header_examples( @app.get("/header_example_examples/") def header_example_examples( - data: str = Header( - None, + data: Union[str, None] = Header( + default=None, example="header_overriden", examples={ - "example1": {"summary": "Qeury example 1", "value": "header1"}, + "example1": {"summary": "Query example 1", "value": "header1"}, "example2": {"value": "header2"}, }, ), @@ -199,8 +196,8 @@ def header_example_examples( @app.get("/cookie_example/") def cookie_example( - data: str = Cookie( - None, + data: Union[str, None] = Cookie( + default=None, example="cookie1", ), ): @@ -209,8 +206,8 @@ def cookie_example( @app.get("/cookie_examples/") def cookie_examples( - data: str = Cookie( - None, + data: Union[str, None] = Cookie( + default=None, examples={ "example1": {"summary": "cookie example 1", "value": "cookie1"}, "example2": {"value": "cookie2"}, @@ -222,11 +219,11 @@ def cookie_examples( @app.get("/cookie_example_examples/") def cookie_example_examples( - data: str = Cookie( - None, + data: Union[str, None] = Cookie( + default=None, example="cookie_overriden", examples={ - "example1": {"summary": "Qeury example 1", "value": "cookie1"}, + "example1": {"summary": "Query example 1", "value": "cookie1"}, "example2": {"value": "cookie2"}, }, ), @@ -564,7 +561,7 @@ openapi_schema = { "schema": {"title": "Data", "type": "string"}, "examples": { "example1": { - "summary": "Qeury example 1", + "summary": "Query example 1", "value": "query1", }, "example2": {"value": "query2"}, @@ -669,7 +666,7 @@ openapi_schema = { "schema": {"title": "Data", "type": "string"}, "examples": { "example1": { - "summary": "Qeury example 1", + "summary": "Query example 1", "value": "header1", }, "example2": {"value": "header2"}, @@ -774,7 +771,7 @@ openapi_schema = { "schema": {"title": "Data", "type": "string"}, "examples": { "example1": { - "summary": "Qeury example 1", + "summary": "Query example 1", "value": "cookie1", }, "example2": {"value": "cookie2"}, @@ -830,7 +827,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_security_oauth2.py b/tests/test_security_oauth2.py index b7ada7caf..b9ac488ee 100644 --- a/tests/test_security_oauth2.py +++ b/tests/test_security_oauth2.py @@ -117,7 +117,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_security_oauth2_optional.py b/tests/test_security_oauth2_optional.py index ecc766511..a5fd49b8c 100644 --- a/tests/test_security_oauth2_optional.py +++ b/tests/test_security_oauth2_optional.py @@ -121,7 +121,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_security_oauth2_optional_description.py b/tests/test_security_oauth2_optional_description.py index 011db65ec..171f96b76 100644 --- a/tests/test_security_oauth2_optional_description.py +++ b/tests/test_security_oauth2_optional_description.py @@ -122,7 +122,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_serialize_response_dataclass.py b/tests/test_serialize_response_dataclass.py index e520338ec..1e3bf3b28 100644 --- a/tests/test_serialize_response_dataclass.py +++ b/tests/test_serialize_response_dataclass.py @@ -1,8 +1,9 @@ +from dataclasses import dataclass +from datetime import datetime from typing import List, Optional from fastapi import FastAPI from fastapi.testclient import TestClient -from pydantic.dataclasses import dataclass app = FastAPI() @@ -10,54 +11,64 @@ app = FastAPI() @dataclass class Item: name: str + date: datetime price: Optional[float] = None owner_ids: Optional[List[int]] = None @app.get("/items/valid", response_model=Item) def get_valid(): - return {"name": "valid", "price": 1.0} + return {"name": "valid", "date": datetime(2021, 7, 26), "price": 1.0} @app.get("/items/object", response_model=Item) def get_object(): - return Item(name="object", price=1.0, owner_ids=[1, 2, 3]) + return Item( + name="object", date=datetime(2021, 7, 26), price=1.0, owner_ids=[1, 2, 3] + ) @app.get("/items/coerce", response_model=Item) def get_coerce(): - return {"name": "coerce", "price": "1.0"} + return {"name": "coerce", "date": datetime(2021, 7, 26).isoformat(), "price": "1.0"} @app.get("/items/validlist", response_model=List[Item]) def get_validlist(): return [ - {"name": "foo"}, - {"name": "bar", "price": 1.0}, - {"name": "baz", "price": 2.0, "owner_ids": [1, 2, 3]}, + {"name": "foo", "date": datetime(2021, 7, 26)}, + {"name": "bar", "date": datetime(2021, 7, 26), "price": 1.0}, + { + "name": "baz", + "date": datetime(2021, 7, 26), + "price": 2.0, + "owner_ids": [1, 2, 3], + }, ] @app.get("/items/objectlist", response_model=List[Item]) def get_objectlist(): return [ - Item(name="foo"), - Item(name="bar", price=1.0), - Item(name="baz", price=2.0, owner_ids=[1, 2, 3]), + Item(name="foo", date=datetime(2021, 7, 26)), + Item(name="bar", date=datetime(2021, 7, 26), price=1.0), + Item(name="baz", date=datetime(2021, 7, 26), price=2.0, owner_ids=[1, 2, 3]), ] @app.get("/items/no-response-model/object") def get_no_response_model_object(): - return Item(name="object", price=1.0, owner_ids=[1, 2, 3]) + return Item( + name="object", date=datetime(2021, 7, 26), price=1.0, owner_ids=[1, 2, 3] + ) @app.get("/items/no-response-model/objectlist") def get_no_response_model_objectlist(): return [ - Item(name="foo"), - Item(name="bar", price=1.0), - Item(name="baz", price=2.0, owner_ids=[1, 2, 3]), + Item(name="foo", date=datetime(2021, 7, 26)), + Item(name="bar", date=datetime(2021, 7, 26), price=1.0), + Item(name="baz", date=datetime(2021, 7, 26), price=2.0, owner_ids=[1, 2, 3]), ] @@ -67,28 +78,58 @@ client = TestClient(app) def test_valid(): response = client.get("/items/valid") response.raise_for_status() - assert response.json() == {"name": "valid", "price": 1.0, "owner_ids": None} + assert response.json() == { + "name": "valid", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": None, + } def test_object(): response = client.get("/items/object") response.raise_for_status() - assert response.json() == {"name": "object", "price": 1.0, "owner_ids": [1, 2, 3]} + assert response.json() == { + "name": "object", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": [1, 2, 3], + } def test_coerce(): response = client.get("/items/coerce") response.raise_for_status() - assert response.json() == {"name": "coerce", "price": 1.0, "owner_ids": None} + assert response.json() == { + "name": "coerce", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": None, + } def test_validlist(): response = client.get("/items/validlist") response.raise_for_status() assert response.json() == [ - {"name": "foo", "price": None, "owner_ids": None}, - {"name": "bar", "price": 1.0, "owner_ids": None}, - {"name": "baz", "price": 2.0, "owner_ids": [1, 2, 3]}, + { + "name": "foo", + "date": datetime(2021, 7, 26).isoformat(), + "price": None, + "owner_ids": None, + }, + { + "name": "bar", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": None, + }, + { + "name": "baz", + "date": datetime(2021, 7, 26).isoformat(), + "price": 2.0, + "owner_ids": [1, 2, 3], + }, ] @@ -96,23 +137,58 @@ def test_objectlist(): response = client.get("/items/objectlist") response.raise_for_status() assert response.json() == [ - {"name": "foo", "price": None, "owner_ids": None}, - {"name": "bar", "price": 1.0, "owner_ids": None}, - {"name": "baz", "price": 2.0, "owner_ids": [1, 2, 3]}, + { + "name": "foo", + "date": datetime(2021, 7, 26).isoformat(), + "price": None, + "owner_ids": None, + }, + { + "name": "bar", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": None, + }, + { + "name": "baz", + "date": datetime(2021, 7, 26).isoformat(), + "price": 2.0, + "owner_ids": [1, 2, 3], + }, ] def test_no_response_model_object(): response = client.get("/items/no-response-model/object") response.raise_for_status() - assert response.json() == {"name": "object", "price": 1.0, "owner_ids": [1, 2, 3]} + assert response.json() == { + "name": "object", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": [1, 2, 3], + } def test_no_response_model_objectlist(): response = client.get("/items/no-response-model/objectlist") response.raise_for_status() assert response.json() == [ - {"name": "foo", "price": None, "owner_ids": None}, - {"name": "bar", "price": 1.0, "owner_ids": None}, - {"name": "baz", "price": 2.0, "owner_ids": [1, 2, 3]}, + { + "name": "foo", + "date": datetime(2021, 7, 26).isoformat(), + "price": None, + "owner_ids": None, + }, + { + "name": "bar", + "date": datetime(2021, 7, 26).isoformat(), + "price": 1.0, + "owner_ids": None, + }, + { + "name": "baz", + "date": datetime(2021, 7, 26).isoformat(), + "price": 2.0, + "owner_ids": [1, 2, 3], + }, ] diff --git a/tests/test_serialize_response_model.py b/tests/test_serialize_response_model.py index 295667437..3bb46b2e9 100644 --- a/tests/test_serialize_response_model.py +++ b/tests/test_serialize_response_model.py @@ -8,7 +8,7 @@ app = FastAPI() class Item(BaseModel): - name: str = Field(..., alias="aliased_name") + name: str = Field(alias="aliased_name") price: Optional[float] = None owner_ids: Optional[List[int]] = None diff --git a/tests/test_starlette_exception.py b/tests/test_starlette_exception.py index 5759a93f4..2b6712f7b 100644 --- a/tests/test_starlette_exception.py +++ b/tests/test_starlette_exception.py @@ -18,6 +18,16 @@ async def read_item(item_id: str): return {"item": items[item_id]} +@app.get("/http-no-body-statuscode-exception") +async def no_body_status_code_exception(): + raise HTTPException(status_code=204) + + +@app.get("/http-no-body-statuscode-with-detail-exception") +async def no_body_status_code_with_detail_exception(): + raise HTTPException(status_code=204, detail="I should just disappear!") + + @app.get("/starlette-items/{item_id}") async def read_starlette_item(item_id: str): if item_id not in items: @@ -31,6 +41,30 @@ openapi_schema = { "openapi": "3.0.2", "info": {"title": "FastAPI", "version": "0.1.0"}, "paths": { + "/http-no-body-statuscode-exception": { + "get": { + "operationId": "no_body_status_code_exception_http_no_body_statuscode_exception_get", + "responses": { + "200": { + "content": {"application/json": {"schema": {}}}, + "description": "Successful " "Response", + } + }, + "summary": "No Body " "Status " "Code " "Exception", + } + }, + "/http-no-body-statuscode-with-detail-exception": { + "get": { + "operationId": "no_body_status_code_with_detail_exception_http_no_body_statuscode_with_detail_exception_get", + "responses": { + "200": { + "content": {"application/json": {"schema": {}}}, + "description": "Successful " "Response", + } + }, + "summary": "No Body Status Code With Detail Exception", + } + }, "/items/{item_id}": { "get": { "responses": { @@ -102,7 +136,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, @@ -154,3 +188,15 @@ def test_get_starlette_item_not_found(): assert response.status_code == 404, response.text assert response.headers.get("x-error") is None assert response.json() == {"detail": "Item not found"} + + +def test_no_body_status_code_exception_handlers(): + response = client.get("/http-no-body-statuscode-exception") + assert response.status_code == 204 + assert not response.content + + +def test_no_body_status_code_with_detail_exception_handlers(): + response = client.get("/http-no-body-statuscode-with-detail-exception") + assert response.status_code == 204 + assert not response.content diff --git a/tests/test_starlette_urlconvertors.py b/tests/test_starlette_urlconvertors.py index 2320c7005..5a980cbf6 100644 --- a/tests/test_starlette_urlconvertors.py +++ b/tests/test_starlette_urlconvertors.py @@ -5,17 +5,17 @@ app = FastAPI() @app.get("/int/{param:int}") -def int_convertor(param: int = Path(...)): +def int_convertor(param: int = Path()): return {"int": param} @app.get("/float/{param:float}") -def float_convertor(param: float = Path(...)): +def float_convertor(param: float = Path()): return {"float": param} @app.get("/path/{param:path}") -def path_convertor(param: str = Path(...)): +def path_convertor(param: str = Path()): return {"path": param} diff --git a/tests/test_sub_callbacks.py b/tests/test_sub_callbacks.py index 16644b556..7574d6fbc 100644 --- a/tests/test_sub_callbacks.py +++ b/tests/test_sub_callbacks.py @@ -256,7 +256,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tuples.py b/tests/test_tuples.py index 4cd5ee3af..18ec2d048 100644 --- a/tests/test_tuples.py +++ b/tests/test_tuples.py @@ -27,7 +27,7 @@ def post_tuple_of_models(square: Tuple[Coordinate, Coordinate]): @app.post("/tuple-form/") -def hello(values: Tuple[int, int] = Form(...)): +def hello(values: Tuple[int, int] = Form()): return values @@ -200,7 +200,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial001.py b/tests/test_tutorial/test_additional_responses/test_tutorial001.py index 8342dd787..1a8acb523 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial001.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial001.py @@ -76,7 +76,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial002.py b/tests/test_tutorial/test_additional_responses/test_tutorial002.py index 57f877978..2adcf15d0 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial002.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial002.py @@ -72,7 +72,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial003.py b/tests/test_tutorial/test_additional_responses/test_tutorial003.py index 37190b36a..8b2167de0 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial003.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial003.py @@ -77,7 +77,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_additional_responses/test_tutorial004.py b/tests/test_tutorial/test_additional_responses/test_tutorial004.py index c44a18f68..990d5235a 100644 --- a/tests/test_tutorial/test_additional_responses/test_tutorial004.py +++ b/tests/test_tutorial/test_additional_responses/test_tutorial004.py @@ -75,7 +75,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py b/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py index 90feb0172..1ad625db6 100644 --- a/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py +++ b/tests/test_tutorial/test_async_sql_databases/test_tutorial001.py @@ -88,7 +88,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_bigger_applications/test_main.py b/tests/test_tutorial/test_bigger_applications/test_main.py index 7eb675179..cd6d7b5c8 100644 --- a/tests/test_tutorial/test_bigger_applications/test_main.py +++ b/tests/test_tutorial/test_bigger_applications/test_main.py @@ -323,7 +323,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body/test_tutorial001.py b/tests/test_tutorial/test_body/test_tutorial001.py index 7bf62c907..8dbaf15db 100644 --- a/tests/test_tutorial/test_body/test_tutorial001.py +++ b/tests/test_tutorial/test_body/test_tutorial001.py @@ -63,7 +63,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body/test_tutorial001_py310.py b/tests/test_tutorial/test_body/test_tutorial001_py310.py index e292b5346..dd9d9911e 100644 --- a/tests/test_tutorial/test_body/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_body/test_tutorial001_py310.py @@ -61,7 +61,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_fields/test_tutorial001.py b/tests/test_tutorial/test_body_fields/test_tutorial001.py index 9de4907c2..fe5a270f3 100644 --- a/tests/test_tutorial/test_body_fields/test_tutorial001.py +++ b/tests/test_tutorial/test_body_fields/test_tutorial001.py @@ -87,7 +87,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_fields/test_tutorial001_py310.py b/tests/test_tutorial/test_body_fields/test_tutorial001_py310.py index d7a525ea7..993e2a91d 100644 --- a/tests/test_tutorial/test_body_fields/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_body_fields/test_tutorial001_py310.py @@ -84,7 +84,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 b11ecddab..8dc710d75 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial001.py @@ -79,7 +79,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial001_py310.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial001_py310.py index 85ba41ce6..5114ccea2 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial001_py310.py @@ -77,7 +77,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 d98e3e419..64aa9c43b 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial003.py @@ -90,7 +90,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_multiple_params/test_tutorial003_py310.py b/tests/test_tutorial/test_body_multiple_params/test_tutorial003_py310.py index f896f7bf5..fc019d8bb 100644 --- a/tests/test_tutorial/test_body_multiple_params/test_tutorial003_py310.py +++ b/tests/test_tutorial/test_body_multiple_params/test_tutorial003_py310.py @@ -88,7 +88,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 8eb0ad130..c56d41b5b 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial009.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial009.py @@ -53,7 +53,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_nested_models/test_tutorial009_py39.py b/tests/test_tutorial/test_body_nested_models/test_tutorial009_py39.py index 17ca29ce5..5b8d82861 100644 --- a/tests/test_tutorial/test_body_nested_models/test_tutorial009_py39.py +++ b/tests/test_tutorial/test_body_nested_models/test_tutorial009_py39.py @@ -52,7 +52,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_updates/test_tutorial001.py b/tests/test_tutorial/test_body_updates/test_tutorial001.py index 5e92ef7ea..efd0e4676 100644 --- a/tests/test_tutorial/test_body_updates/test_tutorial001.py +++ b/tests/test_tutorial/test_body_updates/test_tutorial001.py @@ -109,7 +109,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_updates/test_tutorial001_py310.py b/tests/test_tutorial/test_body_updates/test_tutorial001_py310.py index ca1d8c585..49279b320 100644 --- a/tests/test_tutorial/test_body_updates/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_body_updates/test_tutorial001_py310.py @@ -108,7 +108,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_body_updates/test_tutorial001_py39.py b/tests/test_tutorial/test_body_updates/test_tutorial001_py39.py index f2b184c4f..872530bcf 100644 --- a/tests/test_tutorial/test_body_updates/test_tutorial001_py39.py +++ b/tests/test_tutorial/test_body_updates/test_tutorial001_py39.py @@ -108,7 +108,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_cookie_params/test_tutorial001.py b/tests/test_tutorial/test_cookie_params/test_tutorial001.py index 3451dc19e..edccffec1 100644 --- a/tests/test_tutorial/test_cookie_params/test_tutorial001.py +++ b/tests/test_tutorial/test_cookie_params/test_tutorial001.py @@ -50,7 +50,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_cookie_params/test_tutorial001_py310.py b/tests/test_tutorial/test_cookie_params/test_tutorial001_py310.py index 587a328da..5caa5c440 100644 --- a/tests/test_tutorial/test_cookie_params/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_cookie_params/test_tutorial001_py310.py @@ -48,7 +48,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_custom_response/test_tutorial009c.py b/tests/test_tutorial/test_custom_response/test_tutorial009c.py new file mode 100644 index 000000000..23c711abe --- /dev/null +++ b/tests/test_tutorial/test_custom_response/test_tutorial009c.py @@ -0,0 +1,10 @@ +from fastapi.testclient import TestClient + +from docs_src.custom_response.tutorial009c import app + +client = TestClient(app) + + +def test_get(): + response = client.get("/") + assert response.content == b'{\n "message": "Hello World"\n}' diff --git a/tests/test_tutorial/test_dataclasses/test_tutorial001.py b/tests/test_tutorial/test_dataclasses/test_tutorial001.py index 3e3fc9acf..bf1564194 100644 --- a/tests/test_tutorial/test_dataclasses/test_tutorial001.py +++ b/tests/test_tutorial/test_dataclasses/test_tutorial001.py @@ -71,7 +71,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dataclasses/test_tutorial003.py b/tests/test_tutorial/test_dataclasses/test_tutorial003.py index dd0f1f2c0..2d86f7b9a 100644 --- a/tests/test_tutorial/test_dataclasses/test_tutorial003.py +++ b/tests/test_tutorial/test_dataclasses/test_tutorial003.py @@ -118,7 +118,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial001.py b/tests/test_tutorial/test_dependencies/test_tutorial001.py index 8b53157cd..c3bca5d5b 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial001.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial001.py @@ -104,7 +104,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial001_py310.py b/tests/test_tutorial/test_dependencies/test_tutorial001_py310.py index a7991170e..32a61c821 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial001_py310.py @@ -102,7 +102,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial004.py b/tests/test_tutorial/test_dependencies/test_tutorial004.py index eb21f6524..f2b1878d5 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial004.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial004.py @@ -62,7 +62,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial004_py310.py b/tests/test_tutorial/test_dependencies/test_tutorial004_py310.py index f66a36a99..e3ae0c741 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial004_py310.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial004_py310.py @@ -60,7 +60,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial006.py b/tests/test_tutorial/test_dependencies/test_tutorial006.py index c08992ec8..2916577a2 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial006.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial006.py @@ -55,7 +55,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_dependencies/test_tutorial012.py b/tests/test_tutorial/test_dependencies/test_tutorial012.py index ada83c626..e4e07395d 100644 --- a/tests/test_tutorial/test_dependencies/test_tutorial012.py +++ b/tests/test_tutorial/test_dependencies/test_tutorial012.py @@ -102,7 +102,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_events/test_tutorial001.py b/tests/test_tutorial/test_events/test_tutorial001.py index e3587a0e8..d52dd1a04 100644 --- a/tests/test_tutorial/test_events/test_tutorial001.py +++ b/tests/test_tutorial/test_events/test_tutorial001.py @@ -47,7 +47,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 68b7d61dc..8522d7b9d 100644 --- a/tests/test_tutorial/test_extra_data_types/test_tutorial001.py +++ b/tests/test_tutorial/test_extra_data_types/test_tutorial001.py @@ -89,7 +89,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_extra_data_types/test_tutorial001_py310.py b/tests/test_tutorial/test_extra_data_types/test_tutorial001_py310.py index 3d4c1d07d..4efdecc53 100644 --- a/tests/test_tutorial/test_extra_data_types/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_extra_data_types/test_tutorial001_py310.py @@ -87,7 +87,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_extra_models/test_tutorial003.py b/tests/test_tutorial/test_extra_models/test_tutorial003.py index a2a325c77..f1433470c 100644 --- a/tests/test_tutorial/test_extra_models/test_tutorial003.py +++ b/tests/test_tutorial/test_extra_models/test_tutorial003.py @@ -78,7 +78,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_extra_models/test_tutorial003_py310.py b/tests/test_tutorial/test_extra_models/test_tutorial003_py310.py index 185bc3a37..56fd83ad3 100644 --- a/tests/test_tutorial/test_extra_models/test_tutorial003_py310.py +++ b/tests/test_tutorial/test_extra_models/test_tutorial003_py310.py @@ -77,7 +77,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_generate_clients/__init__.py b/tests/test_tutorial/test_generate_clients/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/test_tutorial/test_generate_clients/test_tutorial003.py b/tests/test_tutorial/test_generate_clients/test_tutorial003.py new file mode 100644 index 000000000..128fcea30 --- /dev/null +++ b/tests/test_tutorial/test_generate_clients/test_tutorial003.py @@ -0,0 +1,188 @@ +from fastapi.testclient import TestClient + +from docs_src.generate_clients.tutorial003 import app + +client = TestClient(app) + +openapi_schema = { + "openapi": "3.0.2", + "info": {"title": "FastAPI", "version": "0.1.0"}, + "paths": { + "/items/": { + "get": { + "tags": ["items"], + "summary": "Get Items", + "operationId": "items-get_items", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response Items-Get Items", + "type": "array", + "items": {"$ref": "#/components/schemas/Item"}, + } + } + }, + } + }, + }, + "post": { + "tags": ["items"], + "summary": "Create Item", + "operationId": "items-create_item", + "requestBody": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/Item"} + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponseMessage" + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + }, + }, + "/users/": { + "post": { + "tags": ["users"], + "summary": "Create User", + "operationId": "users-create_user", + "requestBody": { + "content": { + "application/json": { + "schema": {"$ref": "#/components/schemas/User"} + } + }, + "required": True, + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponseMessage" + } + } + }, + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + }, + }, + } + }, + }, + "components": { + "schemas": { + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": {"$ref": "#/components/schemas/ValidationError"}, + } + }, + }, + "Item": { + "title": "Item", + "required": ["name", "price"], + "type": "object", + "properties": { + "name": {"title": "Name", "type": "string"}, + "price": {"title": "Price", "type": "number"}, + }, + }, + "ResponseMessage": { + "title": "ResponseMessage", + "required": ["message"], + "type": "object", + "properties": {"message": {"title": "Message", "type": "string"}}, + }, + "User": { + "title": "User", + "required": ["username", "email"], + "type": "object", + "properties": { + "username": {"title": "Username", "type": "string"}, + "email": {"title": "Email", "type": "string"}, + }, + }, + "ValidationError": { + "title": "ValidationError", + "required": ["loc", "msg", "type"], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, + }, + "msg": {"title": "Message", "type": "string"}, + "type": {"title": "Error Type", "type": "string"}, + }, + }, + } + }, +} + + +def test_openapi(): + with client: + response = client.get("/openapi.json") + + assert response.json() == openapi_schema + + +def test_post_items(): + response = client.post("/items/", json={"name": "Foo", "price": 5}) + assert response.status_code == 200, response.text + assert response.json() == {"message": "Item received"} + + +def test_post_users(): + response = client.post( + "/users/", json={"username": "Foo", "email": "foo@example.com"} + ) + assert response.status_code == 200, response.text + assert response.json() == {"message": "User received"} + + +def test_get_items(): + response = client.get("/items/") + assert response.status_code == 200, response.text + assert response.json() == [ + {"name": "Plumbus", "price": 3}, + {"name": "Portal Gun", "price": 9001}, + ] diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial001.py b/tests/test_tutorial/test_handling_errors/test_tutorial001.py index 6b62293d8..ffd79ccff 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial001.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial001.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial002.py b/tests/test_tutorial/test_handling_errors/test_tutorial002.py index d2ce0bf9d..e678499c6 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial002.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial002.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial003.py b/tests/test_tutorial/test_handling_errors/test_tutorial003.py index ca9d94e3c..a01726dc2 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial003.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial003.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial004.py b/tests/test_tutorial/test_handling_errors/test_tutorial004.py index d95debf37..0b5f74798 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial004.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial004.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial005.py b/tests/test_tutorial/test_handling_errors/test_tutorial005.py index cedcaae70..253f3d006 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial005.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial005.py @@ -69,7 +69,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_handling_errors/test_tutorial006.py b/tests/test_tutorial/test_handling_errors/test_tutorial006.py index 8b6c1e7ed..21233d7bb 100644 --- a/tests/test_tutorial/test_handling_errors/test_tutorial006.py +++ b/tests/test_tutorial/test_handling_errors/test_tutorial006.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_header_params/test_tutorial001.py b/tests/test_tutorial/test_header_params/test_tutorial001.py index 0f05b9e8c..273cf3249 100644 --- a/tests/test_tutorial/test_header_params/test_tutorial001.py +++ b/tests/test_tutorial/test_header_params/test_tutorial001.py @@ -51,7 +51,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_header_params/test_tutorial001_py310.py b/tests/test_tutorial/test_header_params/test_tutorial001_py310.py index f5ee17428..77a60eb9d 100644 --- a/tests/test_tutorial/test_header_params/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_header_params/test_tutorial001_py310.py @@ -48,7 +48,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py b/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py index b30427d08..e773e7f8f 100644 --- a/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py +++ b/tests/test_tutorial/test_openapi_callbacks/test_tutorial001.py @@ -143,7 +143,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 f2ec2c7e5..3de19833b 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 @@ -31,7 +31,7 @@ openapi_schema = { }, }, "summary": "Create an item", - "description": "Create an item with all the information:\n\n- **name**: each item must have a name\n- **description**: a long description\n- **price**: required\n- **tax**: if the item doesn't have tax, you can omit this\n- **tags**: a set of unique tag strings for this item\n", + "description": "Create an item with all the information:\n\n- **name**: each item must have a name\n- **description**: a long description\n- **price**: required\n- **tax**: if the item doesn't have tax, you can omit this\n- **tags**: a set of unique tag strings for this item", "operationId": "create_item_items__post", "requestBody": { "content": { @@ -72,7 +72,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 d21640946..e587519a0 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005.py @@ -72,7 +72,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py310.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py310.py index 1f617da70..43a7a610d 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py310.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py310.py @@ -71,7 +71,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py39.py b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py39.py index ffdf05081..62aa73ac5 100644 --- a/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py39.py +++ b/tests/test_tutorial/test_path_operation_configurations/test_tutorial005_py39.py @@ -71,7 +71,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_path_params/test_tutorial004.py b/tests/test_tutorial/test_path_params/test_tutorial004.py index 131bf773b..7f0227ecf 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial004.py +++ b/tests/test_tutorial/test_path_params/test_tutorial004.py @@ -49,7 +49,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_path_params/test_tutorial005.py b/tests/test_tutorial/test_path_params/test_tutorial005.py index ed9d2032b..eae3637be 100644 --- a/tests/test_tutorial/test_path_params/test_tutorial005.py +++ b/tests/test_tutorial/test_path_params/test_tutorial005.py @@ -54,7 +54,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, @@ -138,7 +138,7 @@ openapi_schema2 = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params/test_tutorial005.py b/tests/test_tutorial/test_query_params/test_tutorial005.py index aabc0af4f..07178f8a6 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial005.py +++ b/tests/test_tutorial/test_query_params/test_tutorial005.py @@ -56,7 +56,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params/test_tutorial006.py b/tests/test_tutorial/test_query_params/test_tutorial006.py index 042a0e1f8..73c5302e7 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial006.py +++ b/tests/test_tutorial/test_query_params/test_tutorial006.py @@ -68,7 +68,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params/test_tutorial006_py310.py b/tests/test_tutorial/test_query_params/test_tutorial006_py310.py index 1986d27d0..141525f15 100644 --- a/tests/test_tutorial/test_query_params/test_tutorial006_py310.py +++ b/tests/test_tutorial/test_query_params/test_tutorial006_py310.py @@ -66,7 +66,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 709bf6956..f8d7f85c8 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 @@ -59,7 +59,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial001_py310.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial001_py310.py index 66b24017e..298b5d616 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial001_py310.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial001_py310.py @@ -57,7 +57,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 6ae10296f..ad3645f31 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 @@ -53,7 +53,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py310.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py310.py index 8894ee1b5..9330037ed 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py310.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py310.py @@ -52,7 +52,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py39.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py39.py index b10e70af7..11f23be27 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py39.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial011_py39.py @@ -52,7 +52,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 724c975f8..d69139dda 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 @@ -54,7 +54,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial012_py39.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial012_py39.py index a9cbce02a..b25bb2847 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial012_py39.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial012_py39.py @@ -53,7 +53,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 ad5597913..1b2e36354 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 @@ -54,7 +54,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 98ae5a684..57b8b9d94 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 @@ -53,7 +53,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial014_py310.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial014_py310.py index 33f3d5f77..fe54fc080 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial014_py310.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial014_py310.py @@ -51,7 +51,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial001.py b/tests/test_tutorial/test_request_files/test_tutorial001.py index c1537f445..166014c71 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001.py @@ -99,7 +99,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, @@ -162,7 +162,7 @@ def test_post_file(tmp_path): def test_post_large_file(tmp_path): - default_pydantic_max_size = 2 ** 16 + default_pydantic_max_size = 2**16 path = tmp_path / "test.txt" path.write_bytes(b"x" * (default_pydantic_max_size + 1)) 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 e852a1b31..a254bf3e8 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001_02.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001_02.py @@ -106,7 +106,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial001_02_py310.py b/tests/test_tutorial/test_request_files/test_tutorial001_02_py310.py index 62e9f98d0..15b6a8d53 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001_02_py310.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001_02_py310.py @@ -107,7 +107,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 ec7509ea2..c34165f18 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial001_03.py +++ b/tests/test_tutorial/test_request_files/test_tutorial001_03.py @@ -120,7 +120,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial002.py b/tests/test_tutorial/test_request_files/test_tutorial002.py index 4e33ef464..73d1179a1 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial002.py +++ b/tests/test_tutorial/test_request_files/test_tutorial002.py @@ -119,7 +119,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial002_py39.py b/tests/test_tutorial/test_request_files/test_tutorial002_py39.py index bbdf25cd9..de4127057 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial002_py39.py +++ b/tests/test_tutorial/test_request_files/test_tutorial002_py39.py @@ -119,7 +119,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial003.py b/tests/test_tutorial/test_request_files/test_tutorial003.py index 943b235ab..83aea66cd 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial003.py +++ b/tests/test_tutorial/test_request_files/test_tutorial003.py @@ -132,7 +132,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_files/test_tutorial003_py39.py b/tests/test_tutorial/test_request_files/test_tutorial003_py39.py index d5fbd7889..56aeb54cd 100644 --- a/tests/test_tutorial/test_request_files/test_tutorial003_py39.py +++ b/tests/test_tutorial/test_request_files/test_tutorial003_py39.py @@ -132,7 +132,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_request_forms/test_tutorial001.py b/tests/test_tutorial/test_request_forms/test_tutorial001.py index 3d271b531..215260ffa 100644 --- a/tests/test_tutorial/test_request_forms/test_tutorial001.py +++ b/tests/test_tutorial/test_request_forms/test_tutorial001.py @@ -61,7 +61,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 10cce5e61..09e232b8e 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 @@ -61,7 +61,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial003.py b/tests/test_tutorial/test_response_model/test_tutorial003.py index 44f2fb7ca..e1bde5d13 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003.py @@ -74,7 +74,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial003_py310.py b/tests/test_tutorial/test_response_model/test_tutorial003_py310.py index ffba11662..9827dab8a 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial003_py310.py +++ b/tests/test_tutorial/test_response_model/test_tutorial003_py310.py @@ -73,7 +73,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial004.py b/tests/test_tutorial/test_response_model/test_tutorial004.py index 19303982b..8c98c6de3 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial004.py +++ b/tests/test_tutorial/test_response_model/test_tutorial004.py @@ -71,7 +71,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial004_py310.py b/tests/test_tutorial/test_response_model/test_tutorial004_py310.py index f1508a05d..7fc86fafa 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial004_py310.py +++ b/tests/test_tutorial/test_response_model/test_tutorial004_py310.py @@ -69,7 +69,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial004_py39.py b/tests/test_tutorial/test_response_model/test_tutorial004_py39.py index e5d9c8b5f..405fe79f5 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial004_py39.py +++ b/tests/test_tutorial/test_response_model/test_tutorial004_py39.py @@ -69,7 +69,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial005.py b/tests/test_tutorial/test_response_model/test_tutorial005.py index 9ca5463e6..476b172d3 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial005.py +++ b/tests/test_tutorial/test_response_model/test_tutorial005.py @@ -98,7 +98,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial005_py310.py b/tests/test_tutorial/test_response_model/test_tutorial005_py310.py index 6d7366f12..389a302e0 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial005_py310.py +++ b/tests/test_tutorial/test_response_model/test_tutorial005_py310.py @@ -97,7 +97,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial006.py b/tests/test_tutorial/test_response_model/test_tutorial006.py index 25eb6e333..38eb31e54 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial006.py +++ b/tests/test_tutorial/test_response_model/test_tutorial006.py @@ -98,7 +98,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_response_model/test_tutorial006_py310.py b/tests/test_tutorial/test_response_model/test_tutorial006_py310.py index a3d8d204e..f870f3926 100644 --- a/tests/test_tutorial/test_response_model/test_tutorial006_py310.py +++ b/tests/test_tutorial/test_response_model/test_tutorial006_py310.py @@ -97,7 +97,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, 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 89f5b66fd..badf66b3d 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial004.py @@ -103,7 +103,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_schema_extra_example/test_tutorial004_py310.py b/tests/test_tutorial/test_schema_extra_example/test_tutorial004_py310.py index 4f9a2ff57..d326a5a09 100644 --- a/tests/test_tutorial/test_schema_extra_example/test_tutorial004_py310.py +++ b/tests/test_tutorial/test_schema_extra_example/test_tutorial004_py310.py @@ -102,7 +102,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_security/test_tutorial003.py b/tests/test_tutorial/test_security/test_tutorial003.py index 3fc7f5f40..595107834 100644 --- a/tests/test_tutorial/test_security/test_tutorial003.py +++ b/tests/test_tutorial/test_security/test_tutorial003.py @@ -81,7 +81,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_security/test_tutorial003_py310.py b/tests/test_tutorial/test_security/test_tutorial003_py310.py index e621bcd45..26f5c097f 100644 --- a/tests/test_tutorial/test_security/test_tutorial003_py310.py +++ b/tests/test_tutorial/test_security/test_tutorial003_py310.py @@ -80,7 +80,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_security/test_tutorial005.py b/tests/test_tutorial/test_security/test_tutorial005.py index a37f2d60a..e8697339f 100644 --- a/tests/test_tutorial/test_security/test_tutorial005.py +++ b/tests/test_tutorial/test_security/test_tutorial005.py @@ -141,7 +141,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_security/test_tutorial005_py310.py b/tests/test_tutorial/test_security/test_tutorial005_py310.py index 0c9372e2a..3144a2365 100644 --- a/tests/test_tutorial/test_security/test_tutorial005_py310.py +++ b/tests/test_tutorial/test_security/test_tutorial005_py310.py @@ -134,7 +134,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_security/test_tutorial005_py39.py b/tests/test_tutorial/test_security/test_tutorial005_py39.py index 099ab2526..290136e17 100644 --- a/tests/test_tutorial/test_security/test_tutorial005_py39.py +++ b/tests/test_tutorial/test_security/test_tutorial005_py39.py @@ -134,7 +134,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases.py b/tests/test_tutorial/test_sql_databases/test_sql_databases.py index c88fd0bcd..9d03ce61b 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases.py @@ -261,7 +261,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, @@ -356,12 +356,6 @@ def test_create_item(client): item_to_check = [it for it in user_data["items"] if it["id"] == item_data["id"]][0] assert item_to_check["title"] == item["title"] assert item_to_check["description"] == item["description"] - response = client.get("/users/1") - assert response.status_code == 200, response.text - user_data = response.json() - item_to_check = [it for it in user_data["items"] if it["id"] == item_data["id"]][0] - assert item_to_check["title"] == item["title"] - assert item_to_check["description"] == item["description"] def test_read_items(client): diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware.py b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware.py index b02e1c89e..fbaa8938a 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware.py @@ -260,7 +260,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py310.py b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py310.py index 1d0442eb5..d131b4b6a 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py310.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py310.py @@ -263,7 +263,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py39.py b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py39.py index 8764d07a6..470fb52fd 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py39.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases_middleware_py39.py @@ -263,7 +263,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases_py310.py b/tests/test_tutorial/test_sql_databases/test_sql_databases_py310.py index f7e73dea4..dc6a1db15 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases_py310.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases_py310.py @@ -263,7 +263,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases/test_sql_databases_py39.py b/tests/test_tutorial/test_sql_databases/test_sql_databases_py39.py index c194c85aa..ebf55ed01 100644 --- a/tests/test_tutorial/test_sql_databases/test_sql_databases_py39.py +++ b/tests/test_tutorial/test_sql_databases/test_sql_databases_py39.py @@ -263,7 +263,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_tutorial/test_sql_databases_peewee/test_sql_databases_peewee.py b/tests/test_tutorial/test_sql_databases_peewee/test_sql_databases_peewee.py index 2ebc31b95..d28ea5e76 100644 --- a/tests/test_tutorial/test_sql_databases_peewee/test_sql_databases_peewee.py +++ b/tests/test_tutorial/test_sql_databases_peewee/test_sql_databases_peewee.py @@ -318,7 +318,7 @@ openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_union_body.py b/tests/test_union_body.py index d1dfd5efb..3e424de07 100644 --- a/tests/test_union_body.py +++ b/tests/test_union_body.py @@ -84,7 +84,7 @@ item_openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_union_inherited_body.py b/tests/test_union_inherited_body.py index e3d0acc99..60b327ebc 100644 --- a/tests/test_union_inherited_body.py +++ b/tests/test_union_inherited_body.py @@ -96,7 +96,7 @@ inherited_item_openapi_schema = { "loc": { "title": "Location", "type": "array", - "items": {"type": "string"}, + "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]}, }, "msg": {"title": "Message", "type": "string"}, "type": {"title": "Error Type", "type": "string"}, diff --git a/tests/test_validate_response.py b/tests/test_validate_response.py index 45d303e20..62f51c960 100644 --- a/tests/test_validate_response.py +++ b/tests/test_validate_response.py @@ -1,4 +1,4 @@ -from typing import List, Optional +from typing import List, Optional, Union import pytest from fastapi import FastAPI @@ -19,6 +19,19 @@ def get_invalid(): return {"name": "invalid", "price": "foo"} +@app.get("/items/invalidnone", response_model=Item) +def get_invalid_none(): + return None + + +@app.get("/items/validnone", response_model=Union[Item, None]) +def get_valid_none(send_none: bool = False): + if send_none: + return None + else: + return {"name": "invalid", "price": 3.2} + + @app.get("/items/innerinvalid", response_model=Item) def get_innerinvalid(): return {"name": "double invalid", "price": "foo", "owner_ids": ["foo", "bar"]} @@ -41,6 +54,25 @@ def test_invalid(): client.get("/items/invalid") +def test_invalid_none(): + with pytest.raises(ValidationError): + client.get("/items/invalidnone") + + +def test_valid_none_data(): + response = client.get("/items/validnone") + data = response.json() + assert response.status_code == 200 + assert data == {"name": "invalid", "price": 3.2, "owner_ids": None} + + +def test_valid_none_none(): + response = client.get("/items/validnone", params={"send_none": "true"}) + data = response.json() + assert response.status_code == 200 + assert data is None + + def test_double_invalid(): with pytest.raises(ValidationError): client.get("/items/innerinvalid") diff --git a/tests/test_ws_router.py b/tests/test_ws_router.py index bd7c3c53d..206d743ba 100644 --- a/tests/test_ws_router.py +++ b/tests/test_ws_router.py @@ -3,6 +3,7 @@ from fastapi.testclient import TestClient router = APIRouter() prefix_router = APIRouter() +native_prefix_route = APIRouter(prefix="/native") app = FastAPI() @@ -34,6 +35,14 @@ async def routerindex2(websocket: WebSocket): await websocket.close() +@router.websocket("/router/{pathparam:path}") +async def routerindexparams(websocket: WebSocket, pathparam: str, queryparam: str): + await websocket.accept() + await websocket.send_text(pathparam) + await websocket.send_text(queryparam) + await websocket.close() + + async def ws_dependency(): return "Socket Dependency" @@ -47,8 +56,16 @@ async def router_ws_decorator_depends( await websocket.close() +@native_prefix_route.websocket("/") +async def router_native_prefix_ws(websocket: WebSocket): + await websocket.accept() + await websocket.send_text("Hello, router with native prefix!") + await websocket.close() + + app.include_router(router) app.include_router(prefix_router, prefix="/prefix") +app.include_router(native_prefix_route) def test_app(): @@ -72,6 +89,13 @@ def test_prefix_router(): assert data == "Hello, router with prefix!" +def test_native_prefix_router(): + client = TestClient(app) + with client.websocket_connect("/native/") as websocket: + data = websocket.receive_text() + assert data == "Hello, router with native prefix!" + + def test_router2(): client = TestClient(app) with client.websocket_connect("/router2") as websocket: @@ -90,3 +114,14 @@ def test_router_ws_depends_with_override(): app.dependency_overrides[ws_dependency] = lambda: "Override" with client.websocket_connect("/router-ws-depends/") as websocket: assert websocket.receive_text() == "Override" + + +def test_router_with_params(): + client = TestClient(app) + with client.websocket_connect( + "/router/path/to/file?queryparam=a_query_param" + ) as websocket: + data = websocket.receive_text() + assert data == "path/to/file" + data = websocket.receive_text() + assert data == "a_query_param"