* При необходимости улучшите ваш языковой специфичный промпт, общий промпт или английский документ.
* При необходимости улучшите ваш языковой специфичный промпт, общий промпт или английский документ.
* Затем вручную исправьте оставшиеся проблемы в переводе, чтобы он был хорошим.
* Затем вручную исправьте оставшиеся проблемы в переводе, чтобы он был хорошим.
* Переведите заново, имея хороший перевод на месте. Идеальным результатом будет ситуация, когда LLM больше не вносит изменений в перевод. Это означает, что общий промпт и ваш языковой специфичный промпт настолько хороши, насколько это возможно (иногда он будет делать несколько, казалось бы, случайных изменений, причина в том, что <ahref="https://doublespeak.chat/#/handbook#deterministic-output"class="external-link"target="_blank">LLM — недетерминированные алгоритмы</a>).
* Переведите заново, имея хороший перевод на месте. Идеальным результатом будет ситуация, когда LLM больше не вносит изменений в перевод. Это означает, что общий промпт и ваш языковой специфичный промпт настолько хороши, насколько это возможно (иногда он будет делать несколько, казалось бы, случайных изменений, причина в том, что [LLM — недетерминированные алгоритмы](https://doublespeak.chat/#/handbook#deterministic-output)).
Тесты:
Тесты:
@ -169,15 +169,15 @@ works(foo="bar") # Это работает 🎉
Текст ссылок должен переводиться, адрес ссылки не должен изменяться:
Текст ссылок должен переводиться, адрес ссылки не должен изменяться:
Если вы возвращаете дополнительные статус-коды и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что у FastAPI нет способа заранее знать, что вы собираетесь вернуть.
Если вы возвращаете дополнительные статус-коды и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что у FastAPI нет способа заранее знать, что вы собираетесь вернуть.
Но вы можете задокументировать это в своём коде, используя: [Дополнительные ответы](additional-responses.md){.internal-link target=_blank}.
Но вы можете задокументировать это в своём коде, используя: [Дополнительные ответы](additional-responses.md).
# Подключение WSGI — Flask, Django и другие { #including-wsgi-flask-django-others }
# Подключение WSGI — Flask, Django и другие { #including-wsgi-flask-django-others }
Вы можете монтировать WSGI‑приложения, как вы видели в [Подприложения — Mounts](sub-applications.md){.internal-link target=_blank}, [За прокси‑сервером](behind-a-proxy.md){.internal-link target=_blank}.
Вы можете монтировать WSGI‑приложения, как вы видели в [Подприложения — Mounts](sub-applications.md), [За прокси‑сервером](behind-a-proxy.md).
Для этого вы можете использовать `WSGIMiddleware` и обернуть им ваше WSGI‑приложение, например Flask, Django и т.д.
Для этого вы можете использовать `WSGIMiddleware` и обернуть им ваше WSGI‑приложение, например Flask, Django и т.д.
@ -36,13 +36,13 @@
А всё остальное будет обрабатываться **FastAPI**.
А всё остальное будет обрабатываться **FastAPI**.
Если вы запустите это и перейдёте по <ahref="http://localhost:8000/v1/"class="external-link"target="_blank">http://localhost:8000/v1/</a>, вы увидите HTTP‑ответ от Flask:
Если вы запустите это и перейдёте по [http://localhost:8000/v1/](http://localhost:8000/v1/), вы увидите HTTP‑ответ от Flask:
```txt
```txt
Hello, World from Flask!
Hello, World from Flask!
```
```
А если вы перейдёте по <ahref="http://localhost:8000/v2"class="external-link"target="_blank">http://localhost:8000/v2</a>, вы увидите HTTP‑ответ от FastAPI:
А если вы перейдёте по [http://localhost:8000/v2](http://localhost:8000/v2), вы увидите HTTP‑ответ от FastAPI:
Независимые бенчмарки TechEmpower показывают, что приложения **FastAPI** под управлением Uvicorn — <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"class="external-link"target="_blank">одни из самых быстрых Python‑фреймворков</a>, уступающие только Starlette и самому Uvicorn (используются внутри FastAPI).
Независимые бенчмарки TechEmpower показывают, что приложения **FastAPI** под управлением Uvicorn — [одни из самых быстрых Python‑фреймворков](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7), уступающие только Starlette и самому Uvicorn (используются внутри FastAPI).
Но при просмотре бенчмарков и сравнений следует иметь в виду следующее.
Но при просмотре бенчмарков и сравнений следует иметь в виду следующее.
@ -65,7 +65,7 @@ print(f"Hello {name} from Python")
/// tip | Совет
/// tip | Совет
Второй аргумент <ahref="https://docs.python.org/3.8/library/os.html#os.getenv"class="external-link"target="_blank">`os.getenv()`</a> - это возвращаемое по умолчанию значение.
Второй аргумент [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) - это возвращаемое по умолчанию значение.
Если значение не указано, то по умолчанию оно равно `None`. В данном случае мы указываем `«World»` в качестве значения по умолчанию.
Если значение не указано, то по умолчанию оно равно `None`. В данном случае мы указываем `«World»` в качестве значения по умолчанию.
@ -153,7 +153,7 @@ Hello World from Python
/// tip | Совет
/// tip | Совет
Подробнее об этом можно прочитать на сайте <ahref="https://12factor.net/config"class="external-link"target="_blank">The Twelve-Factor App: Config</a>.
Подробнее об этом можно прочитать на сайте [The Twelve-Factor App: Config](https://12factor.net/config).
///
///
@ -163,7 +163,7 @@ Hello World from Python
Это означает, что **любое значение**, считанное в Python из переменной окружения, **будет `str`**, и любое преобразование к другому типу или любая валидация должны быть выполнены в коде.
Это означает, что **любое значение**, считанное в Python из переменной окружения, **будет `str`**, и любое преобразование к другому типу или любая валидация должны быть выполнены в коде.
Подробнее об использовании переменных окружения для работы с **настройками приложения** вы узнаете в [Расширенное руководство пользователя - Настройки и переменные среды](./advanced/settings.md){.internal-link target=_blank}.
Подробнее об использовании переменных окружения для работы с **настройками приложения** вы узнаете в [Расширенное руководство пользователя - Настройки и переменные среды](./advanced/settings.md).
Эта информация будет полезна при изучении [Виртуальных окружений](virtual-environments.md){.internal-link target=_blank}.
Эта информация будет полезна при изучении [Виртуальных окружений](virtual-environments.md).
## Вывод { #conclusion }
## Вывод { #conclusion }
Благодаря этому вы должны иметь базовое представление о том, что такое **переменные окружения** и как использовать их в Python.
Благодаря этому вы должны иметь базовое представление о том, что такое **переменные окружения** и как использовать их в Python.
Подробнее о них вы также можете прочитать в <ahref="https://en.wikipedia.org/wiki/Environment_variable"class="external-link"target="_blank">статье о переменных окружения на википедии</a>.
Подробнее о них вы также можете прочитать в [статье о переменных окружения на википедии](https://en.wikipedia.org/wiki/Environment_variable).
Во многих случаях не всегда очевидно, как переменные окружения могут быть полезны и применимы. Но они постоянно появляются в различных сценариях разработки, поэтому знать о них полезно.
Во многих случаях не всегда очевидно, как переменные окружения могут быть полезны и применимы. Но они постоянно появляются в различных сценариях разработки, поэтому знать о них полезно.
**FastAPI CLI** это программа командной строки, которую вы можете использовать для запуска вашего FastAPI приложения, для управления FastAPI-проектом, а также для многих других вещей.
**FastAPI <abbrtitle="command line interface - интерфейс командной строки">CLI</abbr>** - это программа командной строки, которую вы можете использовать, чтобы предоставлять доступ к вашему приложению FastAPI, управлять проектом FastAPI и т.д.
`fastapi-cli` устанавливается вместе со стандартным пакетом FastAPI (при запуске команды `pip install "fastapi[standard]"`). Данный пакет предоставляет доступ к программе `fastapi` через терминал.
При установке FastAPI (например, с помощью `pip install "fastapi[standard]"`) вместе с ним устанавливается программа командной строки, которую можно запускать в терминале.
Чтобы запустить приложение FastAPI в режиме разработки, вы можете использовать команду `fastapi dev`:
Чтобы запустить ваше приложение FastAPI в режиме разработки, используйте команду `fastapi dev`:
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
@ -46,13 +46,66 @@ $ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid
</div>
</div>
Приложение командной строки `fastapi` это и есть **FastAPI CLI**.
/// tip | Подсказка
В продакшн вы будете использовать `fastapi run` вместо `fastapi dev`. 🚀
///
Внутри **FastAPI CLI** используется [Uvicorn](https://www.uvicorn.dev), высокопроизводительный, готовый к работе в продакшн ASGI-сервер. 😎
Инструмент командной строки `fastapi` попытается автоматически обнаружить приложение FastAPI для запуска, предполагая, что это объект с именем `app` в файле `main.py` (или в некоторых других вариантах).
Но вы можете явно указать, какое приложение использовать.
## Настройте `entrypoint` приложения в `pyproject.toml` { #configure-the-app-entrypoint-in-pyproject.toml }
Вы можете настроить, где находится ваше приложение, в файле `pyproject.toml`, например так:
```toml
[tool.fastapi]
entrypoint = "main:app"
```
Этот `entrypoint` сообщит команде `fastapi`, что приложение нужно импортировать так:
```python
from main import app
```
FastAPI CLI берет путь к вашей Python-программе (напр. `main.py`) и автоматически находит объект `FastAPI` (обычно это `app`), затем определяет правильный процесс импорта и запускает сервер приложения.
Если ваш код организован так:
```
.
├── backend
│ ├── main.py
│ ├── __init__.py
```
Тогда следует указать `entrypoint` так:
```toml
[tool.fastapi]
entrypoint = "backend.main:app"
```
что будет эквивалентно:
```python
from backend.main import app
```
### `fastapi dev` с указанием пути { #fastapi-dev-with-path }
Вы также можете передать путь к файлу команде `fastapi dev`, и она постарается определить объект приложения FastAPI:
```console
$ fastapi dev main.py
```
Для работы в режиме продакшн вместо `fastapi dev` нужно использовать `fastapi run`. 🚀
Но тогда вам придется каждый раз не забывать передавать правильный путь при вызове команды `fastapi`.
Внутри **FastAPI CLI** используется <ahref="https://www.uvicorn.dev"class="external-link"target="_blank">Uvicorn</a>, высокопроизводительный, готовый к работе в продакшн ASGI-сервер. 😎
Кроме того, другие инструменты могут не найти его, например [Расширение VS Code](editor-support.md) или [FastAPI Cloud](https://fastapicloud.com), поэтому рекомендуется использовать `entrypoint` в `pyproject.toml`.
## `fastapi dev` { #fastapi-dev }
## `fastapi dev` { #fastapi-dev }
@ -70,6 +123,6 @@ FastAPI CLI берет путь к вашей Python-программе (нап
/// tip | Подсказка
/// tip | Подсказка
Вы можете больше узнать об этом в [документации по развертыванию](deployment/index.md){.internal-link target=_blank}.
Вы можете больше узнать об этом в [документации по развертыванию](deployment/index.md).
### Основано на открытых стандартах { #based-on-open-standards }
### Основано на открытых стандартах { #based-on-open-standards }
* <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank"><strong>OpenAPI</strong></a> для создания API, включая объявления <dfntitle="также известны как HTTP-методы, например: POST, GET, PUT, DELETE">операций</dfn><dfntitle="также известен как: эндпоинты, маршруты">пути</dfn>, параметров, тел запросов, безопасности и т.д.
* [**OpenAPI**](https://github.com/OAI/OpenAPI-Specification) для создания API, включая объявления <dfntitle="также известны как HTTP-методы, например: POST, GET, PUT, DELETE">операций</dfn><dfntitle="также известен как: эндпоинты, маршруты">пути</dfn>, параметров, тел запросов, безопасности и т.д.
* Автоматическая документация моделей данных с помощью <ahref="https://json-schema.org/"class="external-link"target="_blank"><strong>JSON Schema</strong></a> (так как сама спецификация OpenAPI основана на JSON Schema).
* Автоматическая документация моделей данных с помощью [**JSON Schema**](https://json-schema.org/) (так как сама спецификация OpenAPI основана на JSON Schema).
* Разработан вокруг этих стандартов, после тщательного их изучения. Это не дополнительная надстройка поверх.
* Разработан вокруг этих стандартов, после тщательного их изучения. Это не дополнительная надстройка поверх.
* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках.
* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках.
@ -15,11 +15,11 @@
Интерактивная документация для API и исследовательские веб-интерфейсы. Поскольку фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из них включены по умолчанию.
Интерактивная документация для API и исследовательские веб-интерфейсы. Поскольку фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из них включены по умолчанию.
* <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank"><strong>Swagger UI</strong></a>, с интерактивным исследованием, вызовом и тестированием вашего API прямо из браузера.
* [**Swagger UI**](https://github.com/swagger-api/swagger-ui), с интерактивным исследованием, вызовом и тестированием вашего API прямо из браузера.
Все основано на стандартных **аннотациях типов Python** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только стандартный современный Python.
Все основано на стандартных **аннотациях типов Python** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только стандартный современный Python.
Если вам нужно освежить знания о типах в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Типы Python](python-types.md){.internal-link target=_blank}.
Если вам нужно освежить знания о типах в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Типы Python](python-types.md).
Вы пишете стандартный Python с типами:
Вы пишете стандартный Python с типами:
@ -75,7 +75,7 @@ my_second_user: User = User(**second_user_data)
Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода.
Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода.
В опросах Python‑разработчиков видно, <ahref="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features"class="external-link"target="_blank">что одной из самых часто используемых функций является «автозавершение»</a>.
В опросах Python‑разработчиков видно, [что одной из самых часто используемых функций является «автозавершение»](https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features).
Вся структура **FastAPI** основана на удовлетворении этой возможности. Автозавершение работает везде.
Вся структура **FastAPI** основана на удовлетворении этой возможности. Автозавершение работает везде.
@ -83,11 +83,11 @@ my_second_user: User = User(**second_user_data)
Вот как ваш редактор может вам помочь:
Вот как ваш редактор может вам помочь:
* в <ahref="https://code.visualstudio.com/"class="external-link"target="_blank">Visual Studio Code</a>:
* в [Visual Studio Code](https://code.visualstudio.com/):
@ -124,7 +124,7 @@ FastAPI имеет продуманные значения **по умолчан
Все схемы безопасности, определённые в OpenAPI, включая:
Все схемы безопасности, определённые в OpenAPI, включая:
* HTTP Basic.
* HTTP Basic.
* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md).
* Ключи API в:
* Ключи API в:
* HTTP-заголовках.
* HTTP-заголовках.
* Параметрах запросов.
* Параметрах запросов.
@ -159,13 +159,13 @@ FastAPI включает в себя чрезвычайно простую в и
## Возможности Starlette { #starlette-features }
## Возможности Starlette { #starlette-features }
**FastAPI** основан на <ahref="https://www.starlette.dev/"class="external-link"target="_blank"><strong>Starlette</strong></a> и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать.
**FastAPI** основан на [**Starlette**](https://www.starlette.dev/) и полностью совместим с ним. Так что любой дополнительный код Starlette, который у вас есть, также будет работать.
На самом деле, `FastAPI` — это подкласс `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же.
На самом деле, `FastAPI` — это подкласс `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же.
С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI — это всего лишь Starlette на стероидах):
С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI — это всего лишь Starlette на стероидах):
* Серьёзно впечатляющая производительность. Это <ahref="https://github.com/encode/starlette#performance"class="external-link"target="_blank">один из самых быстрых фреймворков на Python, наравне с **NodeJS** и **Go**</a>.
* Серьёзно впечатляющая производительность. Это [один из самых быстрых фреймворков на Python, наравне с **NodeJS** и **Go**](https://github.com/encode/starlette#performance).
* Поддержка **WebSocket**.
* Поддержка **WebSocket**.
* Фоновые задачи в том же процессе.
* Фоновые задачи в том же процессе.
* События запуска и выключения.
* События запуска и выключения.
@ -177,7 +177,7 @@ FastAPI включает в себя чрезвычайно простую в и
## Возможности Pydantic { #pydantic-features }
## Возможности Pydantic { #pydantic-features }
**FastAPI** полностью совместим с (и основан на) <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank"><strong>Pydantic</strong></a>. Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать.
**FastAPI** полностью совместим с (и основан на) [**Pydantic**](https://docs.pydantic.dev/). Поэтому любой дополнительный код Pydantic, который у вас есть, также будет работать.
Включая внешние библиотеки, также основанные на Pydantic, такие как <abbrtitle="Object-Relational Mapper - объектно-реляционный маппер">ORM</abbr>’ы, <abbrtitle="Object-Document Mapper - объектно-документный маппер">ODM</abbr>’ы для баз данных.
Включая внешние библиотеки, также основанные на Pydantic, такие как <abbrtitle="Object-Relational Mapper - объектно-реляционный маппер">ORM</abbr>’ы, <abbrtitle="Object-Document Mapper - объектно-документный маппер">ODM</abbr>’ы для баз данных.
## Подписаться на новостную рассылку { #subscribe-to-the-newsletter }
## Подписаться на новостную рассылку { #subscribe-to-the-newsletter }
Вы можете подписаться на редкую [новостную рассылку **FastAPI и его друзья**](newsletter.md){.internal-link target=_blank} и быть в курсе о:
Вы можете подписаться на редкую [новостную рассылку **FastAPI и его друзья**](newsletter.md) и быть в курсе о:
* Новостях о FastAPI и его друзьях 🚀
* Новостях о FastAPI и его друзьях 🚀
* Руководствах 📝
* Руководствах 📝
@ -22,17 +22,17 @@
## Подписаться на FastAPI в X (Twitter) { #follow-fastapi-on-x-twitter }
## Подписаться на FastAPI в X (Twitter) { #follow-fastapi-on-x-twitter }
<ahref="https://x.com/fastapi"class="external-link"target="_blank">Подписаться на @fastapi в **X (Twitter)**</a> для получения наисвежайших новостей о **FastAPI**. 🐦
[Подписаться на @fastapi в **X (Twitter)**](https://x.com/fastapi) для получения наисвежайших новостей о **FastAPI**. 🐦
## Добавить **FastAPI** звезду на GitHub { #star-fastapi-in-github }
## Добавить **FastAPI** звезду на GitHub { #star-fastapi-in-github }
Вы можете добавить FastAPI "звезду" на GitHub (кликнув на кнопку звезды в правом верхнем углу): <ahref="https://github.com/fastapi/fastapi"class="external-link"target="_blank">https://github.com/fastapi/fastapi</a>. ⭐️
Вы можете добавить FastAPI "звезду" на GitHub (кликнув на кнопку звезды в правом верхнем углу): [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi). ⭐️
Чем больше звёзд, тем легче другим пользователям найти проект и увидеть, что он уже оказался полезным для многих.
Чем больше звёзд, тем легче другим пользователям найти проект и увидеть, что он уже оказался полезным для многих.
## Отслеживать свежие выпуски в репозитории на GitHub { #watch-the-github-repository-for-releases }
## Отслеживать свежие выпуски в репозитории на GitHub { #watch-the-github-repository-for-releases }
Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): <ahref="https://github.com/fastapi/fastapi"class="external-link"target="_blank">https://github.com/fastapi/fastapi</a>. 👀
Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi). 👀
Там же Вы можете выбрать "Releases only".
Там же Вы можете выбрать "Releases only".
@ -40,45 +40,45 @@
## Связаться с автором { #connect-with-the-author }
## Связаться с автором { #connect-with-the-author }
Можно связаться со <ahref="https://tiangolo.com"class="external-link"target="_blank">мной (Sebastián Ramírez / `tiangolo`)</a>, автором.
Можно связаться со [мной (Sebastián Ramírez / `tiangolo`)](https://tiangolo.com), автором.
Вы можете:
Вы можете:
* <ahref="https://github.com/tiangolo"class="external-link"target="_blank">Подписаться на меня на **GitHub**</a>.
* [Подписаться на меня на **GitHub**](https://github.com/tiangolo).
* Посмотреть другие мои проекты с открытым кодом, которые могут быть полезны Вам.
* Посмотреть другие мои проекты с открытым кодом, которые могут быть полезны Вам.
* Подписаться, чтобы видеть, когда я создаю новый проект с открытым кодом.
* Подписаться, чтобы видеть, когда я создаю новый проект с открытым кодом.
* <ahref="https://x.com/tiangolo"class="external-link"target="_blank">Подписаться на меня в **X (Twitter)**</a> или в <ahref="https://fosstodon.org/@tiangolo"class="external-link"target="_blank">Mastodon</a>.
* [Подписаться на меня в **X (Twitter)**](https://x.com/tiangolo) или в [Mastodon](https://fosstodon.org/@tiangolo).
* Поделиться со мной, как Вы используете FastAPI (я обожаю это читать).
* Поделиться со мной, как Вы используете FastAPI (я обожаю это читать).
* Узнавать, когда я делаю объявления или выпускаю новые инструменты.
* Узнавать, когда я делаю объявления или выпускаю новые инструменты.
* Вы также можете <ahref="https://x.com/fastapi"class="external-link"target="_blank">подписаться на @fastapi в X (Twitter)</a> (это отдельный аккаунт).
* Вы также можете [подписаться на @fastapi в X (Twitter)](https://x.com/fastapi) (это отдельный аккаунт).
* <ahref="https://www.linkedin.com/in/tiangolo/"class="external-link"target="_blank">Подписаться на меня в **LinkedIn**</a>.
* [Подписаться на меня в **LinkedIn**](https://www.linkedin.com/in/tiangolo/).
* Узнавать, когда я делаю объявления или выпускаю новые инструменты (хотя чаще я использую X (Twitter) 🤷♂).
* Узнавать, когда я делаю объявления или выпускаю новые инструменты (хотя чаще я использую X (Twitter) 🤷♂).
* Читать, что я пишу (или подписаться на меня) на <ahref="https://dev.to/tiangolo"class="external-link"target="_blank">**Dev.to**</a> или <ahref="https://medium.com/@tiangolo"class="external-link"target="_blank">**Medium**</a>.
* Читать, что я пишу (или подписаться на меня) на [**Dev.to**](https://dev.to/tiangolo) или [**Medium**](https://medium.com/@tiangolo).
* Читать другие идеи, статьи и о созданных мной инструментах.
* Читать другие идеи, статьи и о созданных мной инструментах.
* Подписаться, чтобы читать, когда я публикую что-то новое.
* Подписаться, чтобы читать, когда я публикую что-то новое.
## Оставить сообщение в X (Twitter) о **FastAPI** { #tweet-about-fastapi }
## Оставить сообщение в X (Twitter) о **FastAPI** { #tweet-about-fastapi }
<ahref="https://x.com/compose/tweet?text=I'm loving @fastapi because... https://github.com/fastapi/fastapi"class="external-link"target="_blank">Оставьте сообщение в X (Twitter) о **FastAPI**</a> и позвольте мне и другим узнать, почему он Вам нравится. 🎉
[Оставьте сообщение в X (Twitter) о **FastAPI**](https://x.com/compose/tweet?text=I'm loving @fastapi because... https://github.com/fastapi/fastapi) и позвольте мне и другим узнать, почему он Вам нравится. 🎉
Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы его используете и т.д.
Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы его используете и т.д.
## Оставить голос за FastAPI { #vote-for-fastapi }
## Оставить голос за FastAPI { #vote-for-fastapi }
* <ahref="https://www.slant.co/options/34241/~fastapi-review"class="external-link"target="_blank">Голосуйте за **FastAPI** в Slant</a>.
* [Голосуйте за **FastAPI** в Slant](https://www.slant.co/options/34241/~fastapi-review).
* <ahref="https://alternativeto.net/software/fastapi/about/"class="external-link"target="_blank">Голосуйте за **FastAPI** в AlternativeTo</a>.
* [Голосуйте за **FastAPI** в AlternativeTo](https://alternativeto.net/software/fastapi/about/).
* <ahref="https://stackshare.io/pypi-fastapi"class="external-link"target="_blank">Расскажите, что Вы используете **FastAPI** на StackShare</a>.
* [Расскажите, что Вы используете **FastAPI** на StackShare](https://stackshare.io/pypi-fastapi).
## Помочь другим с вопросами на GitHub { #help-others-with-questions-in-github }
## Помочь другим с вопросами на GitHub { #help-others-with-questions-in-github }
Вы можете попробовать помочь другим с их вопросами в:
Вы можете попробовать помочь другим с их вопросами в:
Во многих случаях Вы уже можете знать ответы на эти вопросы. 🤓
Во многих случаях Вы уже можете знать ответы на эти вопросы. 🤓
Если Вы много помогаете людям с их вопросами, Вы станете официальным [Экспертом FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. 🎉
Если Вы много помогаете людям с их вопросами, Вы станете официальным [Экспертом FastAPI](fastapi-people.md#fastapi-experts). 🎉
Только помните, самое важное — постарайтесь быть добрыми. Люди приходят со своими разочарованиями и часто задают вопросы не лучшим образом, но постарайтесь, насколько можете, быть доброжелательными. 🤗
Только помните, самое важное — постарайтесь быть добрыми. Люди приходят со своими разочарованиями и часто задают вопросы не лучшим образом, но постарайтесь, насколько можете, быть доброжелательными. 🤗
@ -104,7 +104,7 @@
Во многих случаях предоставляют только фрагмент кода, но этого недостаточно, чтобы **воспроизвести проблему**.
Во многих случаях предоставляют только фрагмент кода, но этого недостаточно, чтобы **воспроизвести проблему**.
* Попросите предоставить <ahref="https://stackoverflow.com/help/minimal-reproducible-example"class="external-link"target="_blank">минимальный воспроизводимый пример</a>, который Вы сможете **скопировать-вставить** и запустить локально, чтобы увидеть ту же ошибку или поведение, или лучше понять их кейс.
* Попросите предоставить [минимальный воспроизводимый пример](https://stackoverflow.com/help/minimal-reproducible-example), который Вы сможете **скопировать-вставить** и запустить локально, чтобы увидеть ту же ошибку или поведение, или лучше понять их кейс.
* Если чувствуете себя особенно великодушными, можете попытаться **создать такой пример** сами, основываясь только на описании проблемы. Просто помните, что это может занять много времени, и, возможно, сначала лучше попросить уточнить проблему.
* Если чувствуете себя особенно великодушными, можете попытаться **создать такой пример** сами, основываясь только на описании проблемы. Просто помните, что это может занять много времени, и, возможно, сначала лучше попросить уточнить проблему.
@ -124,7 +124,7 @@
## Отслеживать репозиторий на GitHub { #watch-the-github-repository }
## Отслеживать репозиторий на GitHub { #watch-the-github-repository }
Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): <ahref="https://github.com/fastapi/fastapi"class="external-link"target="_blank">https://github.com/fastapi/fastapi</a>. 👀
Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): [https://github.com/fastapi/fastapi](https://github.com/fastapi/fastapi). 👀
Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления, когда кто-либо создаёт новый вопрос или Issue. Вы также можете указать, что хотите получать уведомления только о новых Issues, или обсуждениях, или пулл-реквестах и т.д.
Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления, когда кто-либо создаёт новый вопрос или Issue. Вы также можете указать, что хотите получать уведомления только о новых Issues, или обсуждениях, или пулл-реквестах и т.д.
@ -132,7 +132,7 @@
## Задать вопросы { #ask-questions }
## Задать вопросы { #ask-questions }
Вы можете <ahref="https://github.com/fastapi/fastapi/discussions/new?category=questions"class="external-link"target="_blank">создать новый вопрос</a> в репозитории GitHub, например:
Вы можете [создать новый вопрос](https://github.com/fastapi/fastapi/discussions/new?category=questions) в репозитории GitHub, например:
* Задать **вопрос** или спросить о **проблеме**.
* Задать **вопрос** или спросить о **проблеме**.
* Предложить новую **возможность**.
* Предложить новую **возможность**.
@ -195,12 +195,12 @@
## Создать пулл-реквест { #create-a-pull-request }
## Создать пулл-реквест { #create-a-pull-request }
Вы можете [сделать вклад](contributing.md){.internal-link target=_blank} в исходный код пулл-реквестами, например:
Вы можете [сделать вклад](contributing.md) в исходный код пулл-реквестами, например:
* Исправить опечатку, найденную в документации.
* Исправить опечатку, найденную в документации.
* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли, <ahref="https://github.com/fastapi/fastapi/edit/master/docs/en/data/external_links.yml"class="external-link"target="_blank">изменив этот файл</a>.
* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли, [изменив этот файл](https://github.com/fastapi/fastapi/edit/master/docs/en/data/external_links.yml).
* Убедитесь, что добавили свою ссылку в начало соответствующего раздела.
* Убедитесь, что добавили свою ссылку в начало соответствующего раздела.
* Помочь с [переводом документации](contributing.md#translations){.internal-link target=_blank} на Ваш язык.
* Помочь с [переводом документации](contributing.md#translations) на Ваш язык.
* Вы также можете проверять переводы, сделанные другими.
* Вы также можете проверять переводы, сделанные другими.
* Предложить новые разделы документации.
* Предложить новые разделы документации.
* Исправить существующую проблему/баг.
* Исправить существующую проблему/баг.
@ -217,8 +217,8 @@
Основные задачи, которые Вы можете выполнить прямо сейчас:
Основные задачи, которые Вы можете выполнить прямо сейчас:
* [Помочь другим с вопросами на GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (смотрите секцию выше).
* [Помочь другим с вопросами на GitHub](#help-others-with-questions-in-github) (смотрите секцию выше).
* [Проверять пулл-реквесты](#review-pull-requests){.internal-link target=_blank} (смотрите секцию выше).
* [Проверять пулл-реквесты](#review-pull-requests) (смотрите секцию выше).
Именно эти две задачи **забирают больше всего времени**. Это основная работа по поддержке FastAPI.
Именно эти две задачи **забирают больше всего времени**. Это основная работа по поддержке FastAPI.
@ -226,11 +226,11 @@
## Подключиться к чату { #join-the-chat }
## Подключиться к чату { #join-the-chat }
Подключайтесь к 👥 <ahref="https://discord.gg/VQjSZaeJmf"class="external-link"target="_blank">серверу чата в Discord</a> 👥 и общайтесь с другими участниками сообщества FastAPI.
Подключайтесь к 👥 [серверу чата в Discord](https://discord.gg/VQjSZaeJmf) 👥 и общайтесь с другими участниками сообщества FastAPI.
/// tip | Подсказка
/// tip | Подсказка
По вопросам — задавайте их в <ahref="https://github.com/fastapi/fastapi/discussions/new?category=questions"class="external-link"target="_blank">GitHub Discussions</a>, так гораздо выше шанс, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}.
По вопросам — задавайте их в [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/new?category=questions), так гораздо выше шанс, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#fastapi-experts).
Используйте чат только для прочих общих бесед.
Используйте чат только для прочих общих бесед.
@ -242,13 +242,13 @@
На GitHub шаблон поможет Вам правильно сформулировать вопрос, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно ещё до того, как спросите. И на GitHub я могу следить за тем, чтобы всегда отвечать на всё, даже если это занимает время. А с чатами я не могу сделать этого лично. 😅
На GitHub шаблон поможет Вам правильно сформулировать вопрос, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно ещё до того, как спросите. И на GitHub я могу следить за тем, чтобы всегда отвечать на всё, даже если это занимает время. А с чатами я не могу сделать этого лично. 😅
Кроме того, переписка в чатах хуже ищется, чем на GitHub, поэтому вопросы и ответы могут теряться среди остальных сообщений. И только те, что на GitHub, учитываются для получения лычки [Эксперт FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}, так что вероятнее всего Вы получите больше внимания именно на GitHub.
Кроме того, переписка в чатах хуже ищется, чем на GitHub, поэтому вопросы и ответы могут теряться среди остальных сообщений. И только те, что на GitHub, учитываются для получения лычки [Эксперт FastAPI](fastapi-people.md#fastapi-experts), так что вероятнее всего Вы получите больше внимания именно на GitHub.
С другой стороны, в чатах тысячи пользователей, так что почти всегда есть шанс найти там кого-то для разговора. 😄
С другой стороны, в чатах тысячи пользователей, так что почти всегда есть шанс найти там кого-то для разговора. 😄
## Спонсировать автора { #sponsor-the-author }
## Спонсировать автора { #sponsor-the-author }
Если Ваш **продукт/компания** зависят от **FastAPI** или связаны с ним и Вы хотите донести до пользователей информацию о себе, Вы можете спонсировать автора (меня) через <ahref="https://github.com/sponsors/tiangolo"class="external-link"target="_blank">GitHub Sponsors</a>. В зависимости от уровня поддержки Вы можете получить дополнительные бонусы, например, бейдж в документации. 🎁
Если Ваш **продукт/компания** зависят от **FastAPI** или связаны с ним и Вы хотите донести до пользователей информацию о себе, Вы можете спонсировать автора (меня) через [GitHub Sponsors](https://github.com/sponsors/tiangolo). В зависимости от уровня поддержки Вы можете получить дополнительные бонусы, например, бейдж в документации. 🎁
# История, проектирование и будущее { #history-design-and-future }
# История, проектирование и будущее { #history-design-and-future }
Однажды, <ahref="https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920"class="external-link"target="_blank">один из пользователей **FastAPI** задал вопрос</a>:
Однажды, [один из пользователей **FastAPI** задал вопрос](https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920):
> Какова история этого проекта? Создаётся впечатление, что он явился из ниоткуда и завоевал мир за несколько недель [...]
> Какова история этого проекта? Создаётся впечатление, что он явился из ниоткуда и завоевал мир за несколько недель [...]
@ -14,7 +14,7 @@
Во многом история **FastAPI** - история его предшественников.
Во многом история **FastAPI** - история его предшественников.
Как написано в разделе [Альтернативы](alternatives.md){.internal-link target=_blank}:
Как написано в разделе [Альтернативы](alternatives.md):
<blockquotemarkdown="1">
<blockquotemarkdown="1">
@ -44,7 +44,7 @@
Я проверил несколько идей на самых популярных редакторах кода: PyCharm, VS Code, редакторы на базе Jedi.
Я проверил несколько идей на самых популярных редакторах кода: PyCharm, VS Code, редакторы на базе Jedi.
Согласно последнему <ahref="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools"class="external-link"target="_blank">опросу Python-разработчиков</a>, который охватывает около 80% пользователей.
Согласно последнему [опросу Python-разработчиков](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools), который охватывает около 80% пользователей.
Это означает, что **FastAPI** был специально проверен на редакторах, используемых 80% Python-разработчиками. И поскольку большинство других редакторов, как правило, работают аналогичным образом, все его преимущества должны работать практически для всех редакторов.
Это означает, что **FastAPI** был специально проверен на редакторах, используемых 80% Python-разработчиками. И поскольку большинство других редакторов, как правило, работают аналогичным образом, все его преимущества должны работать практически для всех редакторов.
@ -54,11 +54,11 @@
## Зависимости { #requirements }
## Зависимости { #requirements }
Протестировав несколько вариантов, я решил, что в качестве основы буду использовать <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">**Pydantic**</a> и его преимущества.
Протестировав несколько вариантов, я решил, что в качестве основы буду использовать [**Pydantic**](https://docs.pydantic.dev/) и его преимущества.
По моим предложениям был изменён код этого фреймворка, чтобы сделать его полностью совместимым с JSON Schema, поддержать различные способы определения ограничений и улучшить поддержку в редакторах кода (проверки типов, автозавершение) на основе тестов в нескольких редакторах.
По моим предложениям был изменён код этого фреймворка, чтобы сделать его полностью совместимым с JSON Schema, поддержать различные способы определения ограничений и улучшить поддержку в редакторах кода (проверки типов, автозавершение) на основе тестов в нескольких редакторах.
Во время разработки я также внес вклад в <ahref="https://www.starlette.dev/"class="external-link"target="_blank">**Starlette**</a>, другую ключевую зависимость.
Во время разработки я также внес вклад в [**Starlette**](https://www.starlette.dev/), другую ключевую зависимость.
## Разработка { #development }
## Разработка { #development }
@ -76,4 +76,4 @@
У **FastAPI** великое будущее.
У **FastAPI** великое будущее.
И [ваш вклад в это](help-fastapi.md){.internal-link target=_blank} - очень ценен.
@ -44,7 +44,7 @@ FastAPI — это современный, быстрый (высокопрои
* **Простота**: Разработан так, чтобы его было легко использовать и осваивать. Меньше времени на чтение документации.
* **Простота**: Разработан так, чтобы его было легко использовать и осваивать. Меньше времени на чтение документации.
* **Краткость**: Минимизируйте дублирование кода. Несколько возможностей из каждого объявления параметров. Меньше ошибок.
* **Краткость**: Минимизируйте дублирование кода. Несколько возможностей из каждого объявления параметров. Меньше ошибок.
* **Надежность**: Получите код, готовый к продакшн. С автоматической интерактивной документацией.
* **Надежность**: Получите код, готовый к продакшн. С автоматической интерактивной документацией.
* **На основе стандартов**: Основан на открытых стандартах API и полностью совместим с ними: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> (ранее известный как Swagger) и <ahref="https://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
* **На основе стандартов**: Основан на открытых стандартах API и полностью совместим с ними: [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (ранее известный как Swagger) и [JSON Schema](https://json-schema.org/).
<small>* оценка на основе тестов внутренней команды разработчиков, создающих продакшн-приложения.</small>
<small>* оценка на основе тестов внутренней команды разработчиков, создающих продакшн-приложения.</small>
@ -55,51 +55,51 @@ FastAPI — это современный, быстрый (высокопрои
"_[...] В последнее время я много где использую **FastAPI**. [...] На самом деле я планирую использовать его для всех **ML-сервисов моей команды в Microsoft**. Некоторые из них интегрируются в основной продукт **Windows**, а некоторые — в продукты **Office**._"
"_[...] В последнее время я много где использую **FastAPI**. [...] На самом деле я планирую использовать его для всех **ML-сервисов моей команды в Microsoft**. Некоторые из них интегрируются в основной продукт **Windows**, а некоторые — в продукты **Office**._"
"_Мы начали использовать библиотеку **FastAPI**, чтобы поднять **REST**-сервер, к которому можно обращаться за **предсказаниями**. [для Ludwig]_"
"_Мы начали использовать библиотеку **FastAPI**, чтобы поднять **REST**-сервер, к которому можно обращаться за **предсказаниями**. [для Ludwig]_"
<divstyle="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong><ahref="https://eng.uber.com/ludwig-v0-2/"target="_blank"><small>(ref)</small></a></div>
<divstyle="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong><ahref="https://eng.uber.com/ludwig-v0-2/"><small>(ref)</small></a></div>
---
---
"_**Netflix** рада объявить об открытом релизе нашего фреймворка оркестрации **антикризисного управления**: **Dispatch**! [создан с помощью **FastAPI**]_"
"_**Netflix** рада объявить об открытом релизе нашего фреймворка оркестрации **антикризисного управления**: **Dispatch**! [создан с помощью **FastAPI**]_"
"_Честно говоря, то, что вы создали, выглядит очень солидно и отполировано. Во многих смыслах это то, чем я хотел видеть **Hug** — очень вдохновляет видеть, как кто-то это создал._"
"_Честно говоря, то, что вы создали, выглядит очень солидно и отполировано. Во многих смыслах это то, чем я хотел видеть **Hug** — очень вдохновляет видеть, как кто-то это создал._"
"_Если кто-то собирается делать продакшн-API на Python, я настоятельно рекомендую **FastAPI**. Он **прекрасно спроектирован**, **прост в использовании** и **отлично масштабируется**, стал **ключевым компонентом** нашей стратегии API-first и приводит в действие множество автоматизаций и сервисов, таких как наш Virtual TAC Engineer._"
"_Если кто-то собирается делать продакшн-API на Python, я настоятельно рекомендую **FastAPI**. Он **прекрасно спроектирован**, **прост в использовании** и **отлично масштабируется**, стал **ключевым компонентом** нашей стратегии API-first и приводит в действие множество автоматизаций и сервисов, таких как наш Virtual TAC Engineer._"
## Мини-документальный фильм о FastAPI { #fastapi-mini-documentary }
## Мини-документальный фильм о FastAPI { #fastapi-mini-documentary }
В конце 2025 года вышел <ahref="https://www.youtube.com/watch?v=mpR8ngthqiE"class="external-link"target="_blank">мини-документальный фильм о FastAPI</a>, вы можете посмотреть его онлайн:
В конце 2025 года вышел [мини-документальный фильм о FastAPI](https://www.youtube.com/watch?v=mpR8ngthqiE), вы можете посмотреть его онлайн:
<ahref="https://www.youtube.com/watch?v=mpR8ngthqiE"target="_blank"><imgsrc="https://fastapi.tiangolo.com/img/fastapi-documentary.jpg"alt="FastAPI Mini Documentary"></a>
<ahref="https://www.youtube.com/watch?v=mpR8ngthqiE"><imgsrc="https://fastapi.tiangolo.com/img/fastapi-documentary.jpg"alt="FastAPI Mini Documentary"></a>
## **Typer**, FastAPI для CLI { #typer-the-fastapi-of-clis }
## **Typer**, FastAPI для CLI { #typer-the-fastapi-of-clis }
Если вы создаёте приложение <abbrtitle="Command Line Interface - Интерфейс командной строки">CLI</abbr> для использования в терминале вместо веб-API, посмотрите <ahref="https://typer.tiangolo.com/"class="external-link"target="_blank">**Typer**</a>.
Если вы создаёте приложение <abbrtitle="Command Line Interface - Интерфейс командной строки">CLI</abbr> для использования в терминале вместо веб-API, посмотрите [**Typer**](https://typer.tiangolo.com/).
**Typer** — младший брат FastAPI. И он задуман как **FastAPI для CLI**. ⌨️ 🚀
**Typer** — младший брат FastAPI. И он задуман как **FastAPI для CLI**. ⌨️ 🚀
@ -135,12 +135,12 @@ FastAPI — это современный, быстрый (высокопрои
FastAPI стоит на плечах гигантов:
FastAPI стоит на плечах гигантов:
* <ahref="https://www.starlette.dev/"class="external-link"target="_blank">Starlette</a> для части, связанной с вебом.
* [Starlette](https://www.starlette.dev/) для части, связанной с вебом.
* <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">Pydantic</a> для части, связанной с данными.
* [Pydantic](https://docs.pydantic.dev/) для части, связанной с данными.
## Установка { #installation }
## Установка { #installation }
Создайте и активируйте <ahref="https://fastapi.tiangolo.com/ru/virtual-environments/"class="external-link"target="_blank">виртуальное окружение</a>, затем установите FastAPI:
Создайте и активируйте [виртуальное окружение](https://fastapi.tiangolo.com/ru/virtual-environments/), затем установите FastAPI:
Если не уверены, посмотрите раздел _«Нет времени?»_ о <ahref="https://fastapi.tiangolo.com/ru/async/#in-a-hurry"target="_blank">`async` и `await` в документации</a>.
Если не уверены, посмотрите раздел _«Нет времени?»_ о [`async` и `await` в документации](https://fastapi.tiangolo.com/ru/async/#in-a-hurry).
<summary>О команде <code>fastapi dev main.py</code>...</summary>
<summary>О команде <code>fastapi dev</code>...</summary>
Команда `fastapi dev` читает ваш файл `main.py`, находит в нём приложение **FastAPI** и запускает сервер с помощью <ahref="https://www.uvicorn.dev"class="external-link"target="_blank">Uvicorn</a>.
Команда `fastapi dev` читает ваш файл `main.py`, находит в нём приложение **FastAPI** и запускает сервер с помощью [Uvicorn](https://www.uvicorn.dev).
По умолчанию `fastapi dev` запускается с включённой авто-перезагрузкой для локальной разработки.
По умолчанию `fastapi dev` запускается с включённой авто-перезагрузкой для локальной разработки.
Подробнее в <ahref="https://fastapi.tiangolo.com/ru/fastapi-cli/"target="_blank">документации по FastAPI CLI</a>.
Подробнее в [документации по FastAPI CLI](https://fastapi.tiangolo.com/ru/fastapi-cli/).
</details>
</details>
### Проверка { #check-it }
### Проверка { #check-it }
Откройте браузер на <ahref="http://127.0.0.1:8000/items/5?q=somequery"class="external-link"target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
Откройте браузер на [http://127.0.0.1:8000/items/5?q=somequery](http://127.0.0.1:8000/items/5?q=somequery).
### Интерактивная документация API { #interactive-api-docs }
### Интерактивная документация API { #interactive-api-docs }
Перейдите на <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Перейдите на [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
Вы увидите автоматическую интерактивную документацию API (предоставлена <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
Вы увидите автоматическую интерактивную документацию API (предоставлена [Swagger UI](https://github.com/swagger-api/swagger-ui)):
### Обновление альтернативной документации API { #alternative-api-docs-upgrade }
### Обновление альтернативной документации API { #alternative-api-docs-upgrade }
Теперь откройте <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
Теперь откройте [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc).
* Альтернативная документация также отразит новый параметр запроса и тело запроса:
* Альтернативная документация также отразит новый параметр запроса и тело запроса:
@ -442,7 +442,7 @@ item: Item
* Очень мощную и простую в использовании систему **<dfntitle="также известна как: компоненты, ресурсы, провайдеры, сервисы, инъекции">внедрения зависимостей</dfn>**.
* Очень мощную и простую в использовании систему **<dfntitle="также известна как: компоненты, ресурсы, провайдеры, сервисы, инъекции">внедрения зависимостей</dfn>**.
* Безопасность и аутентификацию, включая поддержку **OAuth2** с **JWT токенами** и **HTTP Basic** аутентификацию.
* Безопасность и аутентификацию, включая поддержку **OAuth2** с **JWT токенами** и **HTTP Basic** аутентификацию.
* Более продвинутые (но столь же простые) приёмы объявления **глубоко вложенных JSON-моделей** (спасибо Pydantic).
* Более продвинутые (но столь же простые) приёмы объявления **глубоко вложенных JSON-моделей** (спасибо Pydantic).
* Интеграцию **GraphQL** с <ahref="https://strawberry.rocks"class="external-link"target="_blank">Strawberry</a> и другими библиотеками.
* Интеграцию **GraphQL** с [Strawberry](https://strawberry.rocks) и другими библиотеками.
* Множество дополнительных функций (благодаря Starlette), таких как:
* Множество дополнительных функций (благодаря Starlette), таких как:
* **WebSockets**
* **WebSockets**
* чрезвычайно простые тесты на основе HTTPX и `pytest`
* чрезвычайно простые тесты на основе HTTPX и `pytest`
При желании вы можете развернуть своё приложение FastAPI в <ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>, присоединяйтесь к списку ожидания, если ещё не сделали этого. 🚀
При желании вы можете развернуть своё приложение FastAPI в [FastAPI Cloud](https://fastapicloud.com), присоединяйтесь к списку ожидания, если ещё не сделали этого. 🚀
Если у вас уже есть аккаунт **FastAPI Cloud** (мы пригласили вас из списка ожидания 😉), вы можете развернуть ваше приложение одной командой.
Если у вас уже есть аккаунт **FastAPI Cloud** (мы пригласили вас из списка ожидания 😉), вы можете развернуть ваше приложение одной командой.
Перед развертыванием убедитесь, что вы вошли в систему:
<divclass="termy">
```console
$ fastapi login
You are logged in to FastAPI Cloud 🚀
```
</div>
Затем разверните приложение:
<divclass="termy">
<divclass="termy">
```console
```console
@ -488,7 +474,7 @@ Deploying to FastAPI Cloud...
#### О FastAPI Cloud { #about-fastapi-cloud }
#### О FastAPI Cloud { #about-fastapi-cloud }
**<ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>** создан тем же автором и командой, что и **FastAPI**.
**[FastAPI Cloud](https://fastapicloud.com)** создан тем же автором и командой, что и **FastAPI**.
Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API при минимальных усилиях.
Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API при минимальных усилиях.
@ -504,9 +490,9 @@ FastAPI — это open source и стандартизированный фре
## Производительность { #performance }
## Производительность { #performance }
Независимые бенчмарки TechEmpower показывают приложения **FastAPI**, работающие под управлением Uvicorn, как <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"class="external-link"target="_blank">один из самых быстрых доступных фреймворков Python</a>, уступающий только самим Starlette и Uvicorn (используются внутри FastAPI). (*)
Независимые бенчмарки TechEmpower показывают приложения **FastAPI**, работающие под управлением Uvicorn, как [один из самых быстрых доступных фреймворков Python](https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7), уступающий только самим Starlette и Uvicorn (используются внутри FastAPI). (*)
Чтобы узнать больше, см. раздел <ahref="https://fastapi.tiangolo.com/ru/benchmarks/"class="internal-link"target="_blank">Бенчмарки</a>.
Чтобы узнать больше, см. раздел [Бенчмарки](https://fastapi.tiangolo.com/ru/benchmarks/).
## Зависимости { #dependencies }
## Зависимости { #dependencies }
@ -518,19 +504,19 @@ FastAPI зависит от Pydantic и Starlette.
Используется Pydantic:
Используется Pydantic:
* <ahref="https://github.com/JoshData/python-email-validator"target="_blank"><code>email-validator</code></a> — для проверки адресов электронной почты.
* [`email-validator`](https://github.com/JoshData/python-email-validator) — для проверки адресов электронной почты.
Используется Starlette:
Используется Starlette:
* <ahref="https://www.python-httpx.org"target="_blank"><code>httpx</code></a> — обязателен, если вы хотите использовать `TestClient`.
* [`httpx`](https://www.python-httpx.org) — обязателен, если вы хотите использовать `TestClient`.
* <ahref="https://jinja.palletsprojects.com"target="_blank"><code>jinja2</code></a> — обязателен, если вы хотите использовать конфигурацию шаблонов по умолчанию.
* [`jinja2`](https://jinja.palletsprojects.com) — обязателен, если вы хотите использовать конфигурацию шаблонов по умолчанию.
* <ahref="https://github.com/Kludex/python-multipart"target="_blank"><code>python-multipart</code></a> - обязателен, если вы хотите поддерживать <dfntitle="преобразование строки, полученной из HTTP-запроса, в данные Python">«парсинг»</dfn> форм через `request.form()`.
* [`python-multipart`](https://github.com/Kludex/python-multipart) - обязателен, если вы хотите поддерживать <dfntitle="преобразование строки, полученной из HTTP-запроса, в данные Python">«парсинг»</dfn> форм через `request.form()`.
Используется FastAPI:
Используется FastAPI:
* <ahref="https://www.uvicorn.dev"target="_blank"><code>uvicorn</code></a> — сервер, который загружает и «отдаёт» ваше приложение. Включает `uvicorn[standard]`, содержащий некоторые зависимости (например, `uvloop`), нужные для высокой производительности.
* [`uvicorn`](https://www.uvicorn.dev) — сервер, который загружает и «отдаёт» ваше приложение. Включает `uvicorn[standard]`, содержащий некоторые зависимости (например, `uvloop`), нужные для высокой производительности.
* `fastapi-cli[standard]` — чтобы предоставить команду `fastapi`.
* `fastapi-cli[standard]` — чтобы предоставить команду `fastapi`.
* Включает `fastapi-cloud-cli`, который позволяет развернуть ваше приложение FastAPI в <ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>.
* Включает `fastapi-cloud-cli`, который позволяет развернуть ваше приложение FastAPI в [FastAPI Cloud](https://fastapicloud.com).
### Без зависимостей `standard` { #without-standard-dependencies }
### Без зависимостей `standard` { #without-standard-dependencies }
@ -546,13 +532,13 @@ FastAPI зависит от Pydantic и Starlette.
Дополнительные опциональные зависимости Pydantic:
Дополнительные опциональные зависимости Pydantic:
* <ahref="https://docs.pydantic.dev/latest/usage/pydantic_settings/"target="_blank"><code>pydantic-settings</code></a> — для управления настройками.
* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) — для управления настройками.
* <ahref="https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/"target="_blank"><code>pydantic-extra-types</code></a> — дополнительные типы для использования с Pydantic.
* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) — дополнительные типы для использования с Pydantic.
Дополнительные опциональные зависимости FastAPI:
Дополнительные опциональные зависимости FastAPI:
* <ahref="https://github.com/ijl/orjson"target="_blank"><code>orjson</code></a> — обязателен, если вы хотите использовать `ORJSONResponse`.
* [`orjson`](https://github.com/ijl/orjson) — обязателен, если вы хотите использовать `ORJSONResponse`.
* <ahref="https://github.com/esnme/ultrajson"target="_blank"><code>ujson</code></a> — обязателен, если вы хотите использовать `UJSONResponse`.
* [`ujson`](https://github.com/esnme/ultrajson) — обязателен, если вы хотите использовать `UJSONResponse`.
Вы можете использовать этот шаблон для старта: в нём уже сделана значительная часть начальной настройки, безопасность, база данных и несколько эндпоинтов API.
Вы можете использовать этот шаблон для старта: в нём уже сделана значительная часть начальной настройки, безопасность, база данных и несколько эндпоинтов API.
* **Документирования** API с использованием OpenAPI:
* **Документирования** API с использованием OpenAPI:
* что затем используется пользовательскими интерфейсами автоматической интерактивной документации.
* что затем используется пользовательскими интерфейсами автоматической интерактивной документации.
Всё это может звучать абстрактно. Не волнуйтесь. Вы увидите всё это в действии в [Учебник - Руководство пользователя](tutorial/index.md){.internal-link target=_blank}.
Всё это может звучать абстрактно. Не волнуйтесь. Вы увидите всё это в действии в [Учебник - Руководство пользователя](tutorial/index.md).
Важно то, что, используя стандартные типы Python в одном месте (вместо добавления дополнительных классов, декораторов и т.д.), **FastAPI** сделает за вас большую часть работы.
Важно то, что, используя стандартные типы Python в одном месте (вместо добавления дополнительных классов, декораторов и т.д.), **FastAPI** сделает за вас большую часть работы.
/// info | Информация
/// info | Информация
Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом будет <ahref="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html"class="external-link"target="_blank">«шпаргалка» от `mypy`</a>.
Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом будет [«шпаргалка» от `mypy`](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html).
Класс `BackgroundTasks` приходит напрямую из <ahref="https://www.starlette.dev/background/"class="external-link"target="_blank">`starlette.background`</a>.
Класс `BackgroundTasks` приходит напрямую из [`starlette.background`](https://www.starlette.dev/background/).
Он импортируется/включается прямо в FastAPI, чтобы вы могли импортировать его из `fastapi` и избежать случайного импорта альтернативного `BackgroundTask` (без `s` на конце) из `starlette.background`.
Он импортируется/включается прямо в FastAPI, чтобы вы могли импортировать его из `fastapi` и избежать случайного импорта альтернативного `BackgroundTask` (без `s` на конце) из `starlette.background`.
@ -69,11 +69,11 @@
По‑прежнему можно использовать один `BackgroundTask` в FastAPI, но тогда вам нужно создать объект в своём коде и вернуть Starlette `Response`, включающий его.
По‑прежнему можно использовать один `BackgroundTask` в FastAPI, но тогда вам нужно создать объект в своём коде и вернуть Starlette `Response`, включающий его.
Подробнее см. в <ahref="https://www.starlette.dev/background/"class="external-link"target="_blank">официальной документации Starlette по фоновым задачам</a>.
Подробнее см. в [официальной документации Starlette по фоновым задачам](https://www.starlette.dev/background/).
## Предостережение { #caveat }
## Предостережение { #caveat }
Если вам нужно выполнять тяжелые вычисления в фоне, и при этом они не обязательно должны запускаться тем же процессом (например, вам не нужно делиться памятью, переменными и т.п.), вам могут подойти более мощные инструменты, такие как <ahref="https://docs.celeryq.dev"class="external-link"target="_blank">Celery</a>.
Если вам нужно выполнять тяжелые вычисления в фоне, и при этом они не обязательно должны запускаться тем же процессом (например, вам не нужно делиться памятью, переменными и т.п.), вам могут подойти более мощные инструменты, такие как [Celery](https://docs.celeryq.dev).
Они обычно требуют более сложной конфигурации, менеджера очереди сообщений/заданий (например, RabbitMQ или Redis), но позволяют запускать фоновые задачи в нескольких процессах и, что особенно важно, на нескольких серверах.
Они обычно требуют более сложной конфигурации, менеджера очереди сообщений/заданий (например, RabbitMQ или Redis), но позволяют запускать фоновые задачи в нескольких процессах и, что особенно важно, на нескольких серверах.
Для простоты мы воспользовались выдуманным заголовком.
Для простоты мы воспользовались выдуманным заголовком.
В реальных случаях для получения наилучших результатов используйте интегрированные [утилиты безопасности](security/index.md){.internal-link target=_blank}.
В реальных случаях для получения наилучших результатов используйте интегрированные [утилиты безопасности](security/index.md).
Обратите внимание, что так же, как и в случае с [зависимостями в декораторах *операций пути*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, никакое значение не будет передано в вашу *функцию-обработчик пути*.
Обратите внимание, что так же, как и в случае с [зависимостями в декораторах *операций пути*](dependencies/dependencies-in-path-operation-decorators.md), никакое значение не будет передано в вашу *функцию-обработчик пути*.
* Все они будут включать предопределённые `responses`.
* Все они будут включать предопределённые `responses`.
* Все эти *операции пути* будут иметь список `dependencies`, вычисляемых/выполняемых перед ними.
* Все эти *операции пути* будут иметь список `dependencies`, вычисляемых/выполняемых перед ними.
* Если вы также объявите зависимости в конкретной *операции пути*, **они тоже будут выполнены**.
* Если вы также объявите зависимости в конкретной *операции пути*, **они тоже будут выполнены**.
* Сначала выполняются зависимости маршрутизатора, затем [`dependencies` в декораторе](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, и затем обычные параметрические зависимости.
* Сначала выполняются зависимости маршрутизатора, затем [`dependencies` в декораторе](dependencies/dependencies-in-path-operation-decorators.md), и затем обычные параметрические зависимости.
* Вы также можете добавить [`Security`-зависимости с `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
* Вы также можете добавить [`Security`-зависимости с `scopes`](../advanced/security/oauth2-scopes.md).
/// tip | Подсказка
/// tip | Подсказка
@ -303,7 +303,7 @@ from ...dependencies import get_token_header
Вы импортируете и создаёте класс `FastAPI` как обычно.
Вы импортируете и создаёте класс `FastAPI` как обычно.
И мы даже можем объявить [глобальные зависимости](dependencies/global-dependencies.md){.internal-link target=_blank}, которые будут объединены с зависимостями для каждого `APIRouter`:
И мы даже можем объявить [глобальные зависимости](dependencies/global-dependencies.md), которые будут объединены с зависимостями для каждого `APIRouter`:
@ -353,7 +353,7 @@ from .routers import items, users
from app.routers import items, users
from app.routers import items, users
```
```
Чтобы узнать больше о Python-пакетах и модулях, прочитайте <ahref="https://docs.python.org/3/tutorial/modules.html"class="external-link"target="_blank">официальную документацию Python о модулях</a>.
Чтобы узнать больше о Python-пакетах и модулях, прочитайте [официальную документацию Python о модулях](https://docs.python.org/3/tutorial/modules.html).
///
///
@ -465,6 +465,37 @@ from .routers.users import router
///
///
## Настройка `entrypoint` в `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }
Так как ваш объект FastAPI `app` находится в `app/main.py`, вы можете настроить `entrypoint` в файле `pyproject.toml` следующим образом:
```toml
[tool.fastapi]
entrypoint = "app.main:app"
```
это эквивалентно импорту:
```python
from app.main import app
```
Таким образом, команда `fastapi` будет знать, где найти ваше приложение.
/// Note | Примечание
Вы также можете передать путь в команду, например:
```console
$ fastapi dev app/main.py
```
Но вам придётся каждый раз помнить и указывать корректный путь при вызове команды `fastapi`.
Кроме того, другие инструменты могут не суметь его найти, например [расширение VS Code](../editor-support.md) или [FastAPI Cloud](https://fastapicloud.com), поэтому рекомендуется использовать `entrypoint` в `pyproject.toml`.
///
## Проверка автоматической документации API { #check-the-automatic-api-docs }
## Проверка автоматической документации API { #check-the-automatic-api-docs }
Теперь запустите приложение:
Теперь запустите приложение:
@ -472,14 +503,14 @@ from .routers.users import router
<divclass="termy">
<divclass="termy">
```console
```console
$ fastapi dev app/main.py
$ fastapi dev
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
```
</div>
</div>
Откройте документацию по адресу <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Откройте документацию по адресу [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
Вы увидите автоматическую документацию API, включая пути из всех подмодулей, с использованием корректных путей (и префиксов) и корректных тегов:
Вы увидите автоматическую документацию API, включая пути из всех подмодулей, с использованием корректных путей (и префиксов) и корректных тегов:
Помимо обычных простых типов, таких как `str`, `int`, `float` и т.д., вы можете использовать более сложные простые типы, которые наследуются от `str`.
Помимо обычных простых типов, таких как `str`, `int`, `float` и т.д., вы можете использовать более сложные простые типы, которые наследуются от `str`.
Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с <ahref="https://docs.pydantic.dev/latest/concepts/types/"class="external-link"target="_blank">обзором типов Pydantic</a>. Вы увидите некоторые примеры в следующей главе.
Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с [обзором типов Pydantic](https://docs.pydantic.dev/latest/concepts/types/). Вы увидите некоторые примеры в следующей главе.
Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из Pydantic вместо типа `str`:
Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из Pydantic вместо типа `str`:
## Обновление с заменой при помощи `PUT` { #update-replacing-with-put }
## Обновление с заменой при помощи `PUT` { #update-replacing-with-put }
Чтобы обновить элемент, вы можете использовать операцию <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT"class="external-link"target="_blank">HTTP `PUT`</a>.
Чтобы обновить элемент, вы можете использовать операцию [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT).
Вы можете использовать `jsonable_encoder`, чтобы преобразовать входные данные в данные, которые можно сохранить как JSON (например, в NoSQL-базе данных). Например, преобразование `datetime` в `str`.
Вы можете использовать `jsonable_encoder`, чтобы преобразовать входные данные в данные, которые можно сохранить как JSON (например, в NoSQL-базе данных). Например, преобразование `datetime` в `str`.
@ -28,11 +28,11 @@
## Частичное обновление с помощью `PATCH` { #partial-updates-with-patch }
## Частичное обновление с помощью `PATCH` { #partial-updates-with-patch }
Также можно использовать операцию <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH"class="external-link"target="_blank">HTTP `PATCH`</a> для *частичного* обновления данных.
Также можно использовать операцию [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) для частичного обновления данных.
Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми.
Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми.
/// note | Технические детали
/// note | Примечание
`PATCH` менее распространен и известен, чем `PUT`.
`PATCH` менее распространен и известен, чем `PUT`.
@ -89,12 +89,12 @@
///
///
/// note | Технические детали
/// note | Примечание
Обратите внимание, что входная модель по-прежнему валидируется.
Обратите внимание, что входная модель по-прежнему валидируется.
Таким образом, если вы хотите получать частичные обновления, в которых могут быть опущены все атрибуты, вам необходимо иметь модель, в которой все атрибуты помечены как необязательные (со значениями по умолчанию или `None`).
Таким образом, если вы хотите получать частичные обновления, в которых могут быть опущены все атрибуты, вам необходимо иметь модель, в которой все атрибуты помечены как необязательные (со значениями по умолчанию или `None`).
Чтобы отличить модели со всеми необязательными значениями для **обновления** от моделей с обязательными значениями для **создания**, можно воспользоваться идеями, описанными в [Дополнительные модели](extra-models.md){.internal-link target=_blank}.
Чтобы отличить модели со всеми необязательными значениями для обновления и модели с обязательными значениями для создания, можно воспользоваться идеями, описанными в [Дополнительные модели](extra-models.md).
Ваш API почти всегда должен отправлять тело **ответа**. Но клиентам не обязательно всегда отправлять **тело запроса**: иногда они запрашивают только путь, возможно с некоторыми параметрами запроса, но без тела.
Ваш API почти всегда должен отправлять тело **ответа**. Но клиентам не обязательно всегда отправлять **тело запроса**: иногда они запрашивают только путь, возможно с некоторыми параметрами запроса, но без тела.
Чтобы объявить тело **запроса**, используйте модели <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">Pydantic</a>, со всей их мощью и преимуществами.
Чтобы объявить тело **запроса**, используйте модели [Pydantic](https://docs.pydantic.dev/), со всей их мощью и преимуществами.
/// info | Информация
/// info | Информация
@ -73,7 +73,7 @@
* Если данные некорректны, вернёт понятную и наглядную ошибку, указывающую, где именно и что было некорректно.
* Если данные некорректны, вернёт понятную и наглядную ошибку, указывающую, где именно и что было некорректно.
* Передаст полученные данные в параметр `item`.
* Передаст полученные данные в параметр `item`.
* Поскольку внутри функции вы объявили его с типом `Item`, у вас будет поддержка со стороны редактора кода (автозавершение и т.п.) для всех атрибутов и их типов.
* Поскольку внутри функции вы объявили его с типом `Item`, у вас будет поддержка со стороны редактора кода (автозавершение и т.п.) для всех атрибутов и их типов.
* Сгенерирует определения <ahref="https://json-schema.org"class="external-link"target="_blank">JSON Schema</a> для вашей модели; вы можете использовать их и в других местах, если это имеет смысл для вашего проекта.
* Сгенерирует определения [JSON Schema](https://json-schema.org) для вашей модели; вы можете использовать их и в других местах, если это имеет смысл для вашего проекта.
* Эти схемы будут частью сгенерированной схемы OpenAPI и будут использоваться автоматической документацией <abbrtitle="User Interfaces - Пользовательские интерфейсы">UIs</abbr>.
* Эти схемы будут частью сгенерированной схемы OpenAPI и будут использоваться автоматической документацией <abbrtitle="User Interfaces - Пользовательские интерфейсы">UIs</abbr>.
@ -102,15 +102,15 @@ JSON Schema ваших моделей будет частью сгенериро
В сам Pydantic даже были внесены некоторые изменения для поддержки этого.
В сам Pydantic даже были внесены некоторые изменения для поддержки этого.
Предыдущие скриншоты сделаны в <ahref="https://code.visualstudio.com"class="external-link"target="_blank">Visual Studio Code</a>.
Предыдущие скриншоты сделаны в [Visual Studio Code](https://code.visualstudio.com).
Но вы получите такую же поддержку редактора кода в <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> и большинстве других редакторов Python:
Но вы получите такую же поддержку редактора кода в [PyCharm](https://www.jetbrains.com/pycharm/) и большинстве других редакторов Python:
<imgsrc="/img/tutorial/body/image05.png">
<imgsrc="/img/tutorial/body/image05.png">
/// tip | Совет
/// tip | Совет
Если вы используете <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> в качестве редактора кода, вы можете использовать плагин <ahref="https://github.com/koxudaxi/pydantic-pycharm-plugin/"class="external-link"target="_blank">Pydantic PyCharm Plugin</a>.
Если вы используете [PyCharm](https://www.jetbrains.com/pycharm/) в качестве редактора кода, вы можете использовать плагин [Pydantic PyCharm Plugin](https://github.com/koxudaxi/pydantic-pycharm-plugin/).
Он улучшает поддержку моделей Pydantic в редакторе кода, включая:
Он улучшает поддержку моделей Pydantic в редакторе кода, включая:
@ -163,4 +163,4 @@ FastAPI понимает, что значение `q` не является об
## Без Pydantic { #without-pydantic }
## Без Pydantic { #without-pydantic }
Если вы не хотите использовать модели Pydantic, вы также можете использовать параметры **Body**. См. раздел документации [Тело запроса - Несколько параметров: Единичные значения в теле](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
Если вы не хотите использовать модели Pydantic, вы также можете использовать параметры **Body**. См. раздел документации [Тело запроса - Несколько параметров: Единичные значения в теле](body-multiple-params.md#singular-values-in-body).
# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
<ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"class="external-link"target="_blank">Понятие CORS или "Cross-Origin Resource Sharing"</a> относится к ситуациям, при которых запущенный в браузере фронтенд содержит JavaScript-код, который взаимодействует с бэкендом, находящимся на другом "источнике" ("origin").
[CORS или "Cross-Origin Resource Sharing"](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) относится к ситуациям, при которых запущенный в браузере фронтенд содержит JavaScript-код, который взаимодействует с бэкендом, находящимся на другом "источнике" ("origin").
## Источник { #origin }
## Источник { #origin }
@ -55,10 +55,10 @@
* `allow_origins` - Список источников, на которые разрешено выполнять кросс-доменные запросы. Например, `['https://example.org', 'https://www.example.org']`. Можно использовать `['*']`, чтобы разрешить любые источники.
* `allow_origins` - Список источников, на которые разрешено выполнять кросс-доменные запросы. Например, `['https://example.org', 'https://www.example.org']`. Можно использовать `['*']`, чтобы разрешить любые источники.
* `allow_origin_regex` - Регулярное выражение для определения источников, на которые разрешено выполнять кросс-доменные запросы. Например, `'https://.*\.example\.org'`.
* `allow_origin_regex` - Регулярное выражение для определения источников, на которые разрешено выполнять кросс-доменные запросы. Например, `'https://.*\.example\.org'`.
* `allow_methods` - Список HTTP-методов, которые разрешены для кросс-доменных запросов. По умолчанию `['GET']`. Можно использовать `['*']`, чтобы разрешить все стандартные методы.
* `allow_methods` - Список HTTP-методов, которые разрешены для кросс-доменных запросов. По умолчанию `['GET']`. Можно использовать `['*']`, чтобы разрешить все стандартные методы.
* `allow_headers` - Список HTTP-заголовков запроса, которые должны поддерживаться при кросс-доменных запросах. По умолчанию `[]`. Можно использовать `['*']`, чтобы разрешить все заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` и `Content-Type` всегда разрешены для <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests"class="external-link"rel="noopener"target="_blank">простых CORS-запросов</a>.
* `allow_headers` - Список HTTP-заголовков запроса, которые должны поддерживаться при кросс-доменных запросах. По умолчанию `[]`. Можно использовать `['*']`, чтобы разрешить все заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` и `Content-Type` всегда разрешены для [простых CORS-запросов](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests).
* `allow_credentials` - Указывает, что куки разрешены в кросс-доменных запросах. По умолчанию `False`.
* `allow_credentials` - Указывает, что куки разрешены в кросс-доменных запросах. По умолчанию `False`.
Ни один из параметров `allow_origins`, `allow_methods` и `allow_headers` не может быть установлен в `['*']`, если `allow_credentials` имеет значение `True`. Все они должны быть <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards"class="external-link"rel="noopener"target="_blank">указаны явно</a>.
Ни один из параметров `allow_origins`, `allow_methods` и `allow_headers` не может быть установлен в `['*']`, если `allow_credentials` имеет значение `True`. Все они должны быть [указаны явно](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards).
* `expose_headers` - Указывает любые заголовки ответа, которые должны быть доступны браузеру. По умолчанию `[]`.
* `expose_headers` - Указывает любые заголовки ответа, которые должны быть доступны браузеру. По умолчанию `[]`.
* `max_age` - Устанавливает максимальное время в секундах, в течение которого браузер кэширует CORS-ответы. По умолчанию `600`.
* `max_age` - Устанавливает максимальное время в секундах, в течение которого браузер кэширует CORS-ответы. По умолчанию `600`.
@ -77,7 +77,7 @@
## Больше информации { #more-info }
## Больше информации { #more-info }
Для получения более подробной информации о <abbrtitle="Cross-Origin Resource Sharing - совместное использование ресурсов между источниками">CORS</abbr> обратитесь к <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"class="external-link"target="_blank">документации CORS от Mozilla</a>.
Для получения более подробной информации о <abbrtitle="Cross-Origin Resource Sharing - совместное использование ресурсов между источниками">CORS</abbr> обратитесь к [документации CORS от Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
Для получения дополнительной информации, ознакомьтесь с <ahref="https://docs.python.org/3/library/__main__.html"class="external-link"target="_blank">официальной документацией Python</a>.
Для получения дополнительной информации, ознакомьтесь с [официальной документацией Python](https://docs.python.org/3/library/__main__.html).
В этом примере мы используем выдуманные пользовательские HTTP-заголовки `X-Key` и `X-Token`.
В этом примере мы используем выдуманные пользовательские HTTP-заголовки `X-Key` и `X-Token`.
Но в реальных проектах, при внедрении системы безопасности, вы получите больше пользы используя интегрированные [средства защиты (следующая глава)](../security/index.md){.internal-link target=_blank}.
Но в реальных проектах, при внедрении системы безопасности, вы получите больше пользы используя интегрированные [средства защиты (следующая глава)](../security/index.md).
///
///
## Исключения в Зависимостях и возвращаемые значения { #dependencies-errors-and-return-values }
## Ошибки в зависимостях и возвращаемые значения { #dependencies-errors-and-return-values }
Вы можете использовать те же *функции* зависимостей, что и обычно.
Вы можете использовать те же *функции* зависимостей, что и обычно.
@ -62,7 +62,7 @@
## Зависимости для группы *операций путей* { #dependencies-for-a-group-of-path-operations }
## Зависимости для группы *операций путей* { #dependencies-for-a-group-of-path-operations }
Позже, читая о том как структурировать большие приложения ([Большие приложения — несколько файлов](../../tutorial/bigger-applications.md){.internal-link target=_blank}), возможно, многофайловые, вы узнаете как объявить единый параметр `dependencies` для всей группы *операций путей*.
Позже, читая о том как структурировать большие приложения ([Большие приложения — несколько файлов](../../tutorial/bigger-applications.md)), возможно, многофайловые, вы узнаете как объявить единый параметр `dependencies` для всей группы *операций путей*.
## Глобальные Зависимости { #global-dependencies }
## Глобальные Зависимости { #global-dependencies }
@ -14,8 +14,8 @@ FastAPI поддерживает зависимости, которые выпо
Любая функция, с которой можно корректно использовать:
Любая функция, с которой можно корректно использовать:
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"class="external-link"target="_blank">`@contextlib.contextmanager`</a> или
* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) или
будет корректной для использования в качестве зависимости **FastAPI**.
будет корректной для использования в качестве зависимости **FastAPI**.
@ -87,7 +87,7 @@ FastAPI поддерживает зависимости, которые выпо
/// note | Технические детали
/// note | Технические детали
Это работает благодаря <ahref="https://docs.python.org/3/library/contextlib.html"class="external-link"target="_blank">менеджерам контекста</a> в Python.
Это работает благодаря [менеджерам контекста](https://docs.python.org/3/library/contextlib.html) в Python.
**FastAPI** использует их внутренне для достижения этого.
**FastAPI** использует их внутренне для достижения этого.
@ -240,7 +240,7 @@ participant operation as Функция-обработчик пути
«Контекстные менеджеры» — это любые объекты Python, которые можно использовать в операторе `with`.
«Контекстные менеджеры» — это любые объекты Python, которые можно использовать в операторе `with`.
Например, <ahref="https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files"class="external-link"target="_blank">можно использовать `with` для чтения файла</a>:
Например, [можно использовать `with` для чтения файла](https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files):
```Python
```Python
with open("./somefile.txt") as f:
with open("./somefile.txt") as f:
@ -264,7 +264,7 @@ with open("./somefile.txt") as f:
///
///
В Python можно создавать менеджеры контекста, <ahref="https://docs.python.org/3/reference/datamodel.html#context-managers"class="external-link"target="_blank">создав класс с двумя методами: `__enter__()` и `__exit__()`</a>.
В Python можно создавать менеджеры контекста, [создав класс с двумя методами: `__enter__()` и `__exit__()`](https://docs.python.org/3/reference/datamodel.html#context-managers).
Их также можно использовать внутри зависимостей **FastAPI** с `yield`, применяя операторы
Их также можно использовать внутри зависимостей **FastAPI** с `yield`, применяя операторы
`with` или `async with` внутри функции зависимости:
`with` или `async with` внутри функции зависимости:
@ -275,8 +275,8 @@ with open("./somefile.txt") as f:
Другой способ создания менеджера контекста — с помощью:
Другой способ создания менеджера контекста — с помощью:
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"class="external-link"target="_blank">`@contextlib.contextmanager`</a> или
* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) или
Для некоторых типов приложений может потребоваться добавить зависимости ко всему приложению.
Для некоторых типов приложений может потребоваться добавить зависимости ко всему приложению.
Подобно тому, как вы можете [добавлять `dependencies` (зависимости) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, вы можете добавлять зависимости сразу ко всему `FastAPI` приложению.
Подобно тому, как вы можете [добавлять `dependencies` (зависимости) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md), вы можете добавлять зависимости сразу ко всему `FastAPI` приложению.
В этом случае они будут применяться ко всем *операциям пути* в приложении:
В этом случае они будут применяться ко всем *операциям пути* в приложении:
Все способы [добавления `dependencies` (зависимостей) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} по-прежнему применимы, но в данном случае зависимости применяются ко всем *операциям пути* приложения.
Все способы [добавления `dependencies` (зависимостей) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md) по-прежнему применимы, но в данном случае зависимости применяются ко всем *операциям пути* приложения.
## Зависимости для групп *операций пути* { #dependencies-for-groups-of-path-operations }
## Зависимости для групп *операций пути* { #dependencies-for-groups-of-path-operations }
Позднее, читая о том, как структурировать более крупные приложения ([приложения, содержащие много файлов](../../tutorial/bigger-applications.md){.internal-link target=_blank}), возможно, состоящие из нескольких файлов, вы узнаете, как объявить один параметр `dependencies` для целой группы *операций пути*.
Позднее, читая о том, как структурировать более крупные приложения ([Более крупные приложения - несколько файлов](../../tutorial/bigger-applications.md)), возможно, состоящие из нескольких файлов, вы узнаете, как объявить один параметр `dependencies` для целой группы *операций пути*.
* Обеспечить общую логику (один и тот же алгоритм снова и снова).
* Обеспечить общую логику (один и тот же алгоритм снова и снова).
* Разделять соединения с базой данных.
* Разделять соединения с базой данных.
* Обеспечить безопасность, аутентификацию, требования к ролям и т.п.
* Обеспечить безопасность, аутентификацию, требования к ролям и т.п.
* И многое другое...
* И многое другое...
Всё это при минимизации повторения кода.
Всё это при минимизации повторения кода.
@ -57,7 +57,7 @@ FastAPI добавил поддержку `Annotated` (и начал реком
Если у вас более старая версия, вы получите ошибки при попытке использовать `Annotated`.
Если у вас более старая версия, вы получите ошибки при попытке использовать `Annotated`.
Убедитесь, что вы [обновили версию FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} как минимум до 0.95.1, прежде чем использовать `Annotated`.
Убедитесь, что вы [обновили версию FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions) как минимум до 0.95.1, прежде чем использовать `Annotated`.
///
///
@ -67,11 +67,11 @@ FastAPI добавил поддержку `Annotated` (и начал реком
### Объявите зависимость в «зависимом» { #declare-the-dependency-in-the-dependant }
### Объявите зависимость в «зависимом» { #declare-the-dependency-in-the-dependant }
Точно так же, как вы используете `Body`, `Query` и т.д. с параметрами вашей *функции обработки пути*, используйте `Depends` с новым параметром:
Точно так же, как вы используете `Body`, `Query` и т.д. с параметрами вашей *функции обработки пути*, используйте `Depends` с новым параметром:
Вы можете использовать `async def` или обычное `def`.
Вы можете использовать `async def` или обычное `def`.
И вы можете объявлять зависимости с `async def` внутри обычных *функций обработки пути*`def`, или зависимости `def` внутри *функций обработки пути*`async def` и т.д.
И вы можете объявлять зависимости с `async def` внутри обычных *функций обработки пути*`def`, или зависимости `def` внутри *функций обработки пути*`async def` и т.д.
Это не важно. **FastAPI** знает, что делать.
Это не важно. **FastAPI** знает, что делать.
/// note | Примечание
/// note | Примечание
Если вы не уверены, посмотрите раздел [Async: *"In a hurry?"*](../../async.md#in-a-hurry){.internal-link target=_blank} о `async` и `await` в документации.
Если вы не уверены, посмотрите раздел [Async: «Нет времени?»](../../async.md#in-a-hurry) о `async` и `await` в документации.
Например, она не принимает объекты `datetime`, так как они не совместимы с JSON.
Например, она не принимает объекты `datetime`, так как они не совместимы с JSON.
В таком случае объект `datetime` следует преобразовать в строку, соответствующую <ahref="https://en.wikipedia.org/wiki/ISO_8601"class="external-link"target="_blank">формату ISO</a>.
В таком случае объект `datetime` следует преобразовать в `str`, содержащую данные в [формате ISO](https://en.wikipedia.org/wiki/ISO_8601).
Точно так же эта база данных не может принять Pydantic-модель (объект с атрибутами), а только `dict`.
Точно так же эта база данных не может принять Pydantic-модель (объект с атрибутами), а только `dict`.
@ -24,7 +24,7 @@
В данном примере она преобразует Pydantic-модель в `dict`, а `datetime` - в `str`.
В данном примере она преобразует Pydantic-модель в `dict`, а `datetime` - в `str`.
Результатом её вызова является объект, который может быть закодирован с помощью функции из стандартной библиотеки Python – <ahref="https://docs.python.org/3/library/json.html#json.dumps"class="external-link"target="_blank">`json.dumps()`</a>.
Результатом её вызова является объект, который может быть закодирован с помощью функции из стандартной библиотеки Python – [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps).
Функция не возвращает большой `str`, содержащий данные в формате JSON (в виде строки). Она возвращает стандартную структуру данных Python (например, `dict`) со значениями и подзначениями, которые совместимы с JSON.
Функция не возвращает большой `str`, содержащий данные в формате JSON (в виде строки). Она возвращает стандартную структуру данных Python (например, `dict`) со значениями и подзначениями, которые совместимы с JSON.
* В запросах и ответах будет представлен в виде общего количества секунд типа `float`.
* В запросах и ответах будет представлен в виде общего количества секунд типа `float`.
* Pydantic также позволяет представить его как "Кодировку разницы во времени ISO 8601", <ahref="https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers"class="external-link"target="_blank">см. документацию для получения дополнительной информации</a>.
* Pydantic также позволяет представить его как "Кодировку разницы во времени ISO 8601", [см. документацию для получения дополнительной информации](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers).
* `frozenset`:
* `frozenset`:
* В запросах и ответах обрабатывается так же, как и `set`:
* В запросах и ответах обрабатывается так же, как и `set`:
* В запросах будет прочитан список, исключены дубликаты и преобразован в `set`.
* В запросах будет прочитан список, исключены дубликаты и преобразован в `set`.
@ -49,7 +49,7 @@
* `Decimal`:
* `Decimal`:
* Встроенный в Python `Decimal`.
* Встроенный в Python `Decimal`.
* В запросах и ответах обрабатывается так же, как и `float`.
* В запросах и ответах обрабатывается так же, как и `float`.
* Вы можете проверить все допустимые типы данных Pydantic здесь: <ahref="https://docs.pydantic.dev/latest/usage/types/types/"class="external-link"target="_blank">Типы данных Pydantic</a>.
* Вы можете проверить все допустимые типы данных Pydantic здесь: [Типы данных Pydantic](https://docs.pydantic.dev/latest/usage/types/types/).
Никогда не храните пароли пользователей в чистом виде. Всегда храните "безопасный хэш", который вы затем сможете проверить.
Никогда не храните пароли пользователей в чистом виде. Всегда храните "безопасный хэш", который вы затем сможете проверить.
Если вам это не знакомо, вы можете узнать про "хэш пароля" в [главах о безопасности](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}.
Если вам это не знакомо, вы можете узнать про "хэш пароля" в [главах о безопасности](security/simple-oauth2.md#password-hashing).
///
///
@ -162,11 +162,11 @@ UserInDB(
Он будет определён в OpenAPI как `anyOf`.
Он будет определён в OpenAPI как `anyOf`.
Для этого используйте стандартную аннотацию типов в Python <ahref="https://docs.python.org/3/library/typing.html#typing.Union"class="external-link"target="_blank">`typing.Union`</a>:
Для этого используйте стандартную аннотацию типов в Python [`typing.Union`](https://docs.python.org/3/library/typing.html#typing.Union):
/// note | Примечание
/// note | Примечание
При объявлении <ahref="https://docs.pydantic.dev/latest/concepts/types/#unions"class="external-link"target="_blank">`Union`</a> сначала указывайте наиболее специфичный тип, затем менее специфичный. В примере ниже более специфичный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`.
При объявлении [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) сначала указывайте наиболее специфичный тип, затем менее специфичный. В примере ниже более специфичный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`.
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
@ -58,7 +58,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
### Проверьте { #check-it }
### Проверьте { #check-it }
Откройте браузер по адресу: <ahref="http://127.0.0.1:8000"class="external-link"target="_blank">http://127.0.0.1:8000</a>.
Откройте браузер по адресу: [http://127.0.0.1:8000](http://127.0.0.1:8000).
Вы увидите JSON-ответ вида:
Вы увидите JSON-ответ вида:
@ -68,17 +68,17 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
### Интерактивная документация API { #interactive-api-docs }
### Интерактивная документация API { #interactive-api-docs }
Теперь перейдите по адресу: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Теперь перейдите по адресу: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
Вы увидите автоматически сгенерированную интерактивную документацию по API (предоставлено <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
Вы увидите автоматически сгенерированную интерактивную документацию по API (предоставлено [Swagger UI](https://github.com/swagger-api/swagger-ui)):
### Альтернативная документация API { #alternative-api-docs }
### Альтернативная документация API { #alternative-api-docs }
И теперь перейдите по адресу <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
И теперь перейдите по адресу [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc).
Вы увидите альтернативную автоматически сгенерированную документацию (предоставлено <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
Вы увидите альтернативную автоматически сгенерированную документацию (предоставлено [ReDoc](https://github.com/Rebilly/ReDoc)):
@ -92,15 +92,15 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
#### «Схема» API { #api-schema }
#### «Схема» API { #api-schema }
В данном случае <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> — это спецификация, которая определяет, как описывать схему вашего API.
В данном случае [OpenAPI](https://github.com/OAI/OpenAPI-Specification) — это спецификация, которая определяет, как описывать схему вашего API.
Это определение схемы включает пути вашего API, возможные параметры, которые они принимают, и т.п.
Это определение схемы включает пути вашего API, возможные параметры, которые они принимают, и т.п.
#### «Схема» данных { #data-schema }
#### «Схема» данных { #data-schema }
Термин «схема» также может относиться к форме некоторых данных, например, к содержимому JSON.
Термин «схема» также может относиться к форме некоторых данных, например, к содержимому JSON.
В таком случае это будут атрибуты JSON, их типы данных и т.п.
В таком случае это будут атрибуты JSON, их типы данных и т.п.
#### OpenAPI и JSON Schema { #openapi-and-json-schema }
#### OpenAPI и JSON Schema { #openapi-and-json-schema }
@ -110,7 +110,7 @@ OpenAPI определяет схему API для вашего API. И эта
Если вам интересно, как выглядит исходная схема OpenAPI, FastAPI автоматически генерирует JSON (схему) с описанием всего вашего API.
Если вам интересно, как выглядит исходная схема OpenAPI, FastAPI автоматически генерирует JSON (схему) с описанием всего вашего API.
Вы можете посмотреть её напрямую по адресу: <ahref="http://127.0.0.1:8000/openapi.json"class="external-link"target="_blank">http://127.0.0.1:8000/openapi.json</a>.
Вы можете посмотреть её напрямую по адресу: [http://127.0.0.1:8000/openapi.json](http://127.0.0.1:8000/openapi.json).
Вы увидите JSON, начинающийся примерно так:
Вы увидите JSON, начинающийся примерно так:
@ -143,9 +143,58 @@ OpenAPI определяет схему API для вашего API. И эта
Вы также можете использовать её для автоматической генерации кода для клиентов, которые взаимодействуют с вашим API. Например, для фронтенд-, мобильных или IoT-приложений.
Вы также можете использовать её для автоматической генерации кода для клиентов, которые взаимодействуют с вашим API. Например, для фронтенд-, мобильных или IoT-приложений.
### Настройте app `entrypoint` в `pyproject.toml` { #configure-the-app-entrypoint-in-pyproject-toml }
Вы можете указать расположение вашего приложения в файле `pyproject.toml`, например:
```toml
[tool.fastapi]
entrypoint = "main:app"
```
Этот `entrypoint` подскажет команде `fastapi`, что приложение нужно импортировать так:
```python
from main import app
```
Если структура вашего кода выглядит так:
```
.
├── backend
│ ├── main.py
│ ├── __init__.py
```
Тогда следует указать такой `entrypoint`:
```toml
[tool.fastapi]
entrypoint = "backend.main:app"
```
что будет эквивалентно:
```python
from backend.main import app
```
### `fastapi dev` с путём { #fastapi-dev-with-path }
Вы также можете передать путь к файлу в команду `fastapi dev`, и она попытается определить объект приложения FastAPI для использования:
```console
$ fastapi dev main.py
```
Но в этом случае вам придётся каждый раз помнить о передаче корректного пути при вызове команды `fastapi`.
Кроме того, другие инструменты могут его не найти, например [Расширение VS Code](../editor-support.md) или [FastAPI Cloud](https://fastapicloud.com), поэтому рекомендуется использовать `entrypoint` в `pyproject.toml`.
При желании вы можете развернуть своё приложение FastAPI в <ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>, перейдите и присоединитесь к списку ожидания, если ещё не сделали этого. 🚀
При желании вы можете развернуть своё приложение FastAPI в [FastAPI Cloud](https://fastapicloud.com), перейдите и присоединитесь к списку ожидания, если ещё не сделали этого. 🚀
Если у вас уже есть аккаунт **FastAPI Cloud** (мы пригласили вас из списка ожидания 😉), вы можете развернуть приложение одной командой.
Если у вас уже есть аккаунт **FastAPI Cloud** (мы пригласили вас из списка ожидания 😉), вы можете развернуть приложение одной командой.
@ -191,7 +240,7 @@ Deploying to FastAPI Cloud...
`FastAPI` — это класс, который напрямую наследуется от `Starlette`.
`FastAPI` — это класс, который напрямую наследуется от `Starlette`.
Вы можете использовать весь функционал <ahref="https://www.starlette.dev/"class="external-link"target="_blank">Starlette</a> и в `FastAPI`.
Вы можете использовать весь функционал [Starlette](https://www.starlette.dev/) и в `FastAPI`.
///
///
@ -336,7 +385,7 @@ https://example.com/items/foo
/// note | Примечание
/// note | Примечание
Если вы не знаете, в чём разница, посмотрите [Асинхронность: *"Нет времени?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
Если вы не знаете, в чём разница, посмотрите [Асинхронность: *"Нет времени?"*](../async.md#in-a-hurry).
Также можно вернуть модели Pydantic (подробнее об этом позже).
Также можно вернуть модели Pydantic (подробнее об этом позже).
Многие другие объекты и модели будут автоматически преобразованы в JSON (включая ORM и т.п.). Попробуйте использовать те, что вам привычнее, с высокой вероятностью они уже поддерживаются.
Многие другие объекты и модели будут автоматически преобразованы в JSON (включая ORM и т.п.). Попробуйте использовать те, что вам привычнее, с высокой вероятностью они уже поддерживаются.
Разверните приложение в **<ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>** одной командой: `fastapi deploy`. 🎉
Разверните приложение в **[FastAPI Cloud](https://fastapicloud.com)** одной командой: `fastapi deploy`. 🎉
#### О FastAPI Cloud { #about-fastapi-cloud }
#### О FastAPI Cloud { #about-fastapi-cloud }
**<ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>** создан тем же автором и командой, что и **FastAPI**.
**[FastAPI Cloud](https://fastapicloud.com)** создан тем же автором и командой, что и **FastAPI**.
Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями.
Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями.
## Установка пользовательских обработчиков исключений { #install-custom-exception-handlers }
## Установка пользовательских обработчиков исключений { #install-custom-exception-handlers }
Вы можете добавить пользовательские обработчики исключений с помощью <ahref="https://www.starlette.dev/exceptions/"class="external-link"target="_blank">тех же утилит обработки исключений из Starlette</a>.
Вы можете добавить пользовательские обработчики исключений с помощью [тех же утилит обработки исключений из Starlette](https://www.starlette.dev/exceptions/).
Допустим, у вас есть пользовательское исключение `UnicornException`, которое вы (или используемая вами библиотека) можете `вызвать`.
Допустим, у вас есть пользовательское исключение `UnicornException`, которое вы (или используемая вами библиотека) можете `вызвать`.
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
<spanstyle="background-color:#009485"><fontcolor="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
@ -62,7 +62,7 @@ $ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid
Первый шаг — установить FastAPI.
Первый шаг — установить FastAPI.
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, и затем **установите FastAPI**:
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, и затем **установите FastAPI**:
При установке с помощью `pip install "fastapi[standard]"` добавляются некоторые стандартные необязательные зависимости по умолчанию, включая `fastapi-cloud-cli`, который позволяет развернуть приложение на <ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>.
При установке с помощью `pip install "fastapi[standard]"` добавляются некоторые стандартные необязательные зависимости по умолчанию, включая `fastapi-cloud-cli`, который позволяет развернуть приложение на [FastAPI Cloud](https://fastapicloud.com).
Если вы не хотите иметь эти необязательные зависимости, установите просто `pip install fastapi`.
Если вы не хотите иметь эти необязательные зависимости, установите просто `pip install fastapi`.
У FastAPI есть [официальное расширение для VS Code](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode) (и Cursor), которое предоставляет множество функций, включая обзор операций пути, поиск операций пути, навигацию CodeLens в тестах (переход к определению из тестов), а также развертывание в FastAPI Cloud и просмотр логов - всё прямо из вашего редактора кода.
///
## Продвинутое руководство пользователя { #advanced-user-guide }
## Продвинутое руководство пользователя { #advanced-user-guide }
Существует также **Продвинутое руководство пользователя**, которое вы сможете прочитать после **Учебник - Руководство пользователя**.
Существует также **Продвинутое руководство пользователя**, которое вы сможете прочитать после **Учебник - Руководство пользователя**.
| `version` | `string` | Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру `2.5.0`. |
| `version` | `string` | Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру `2.5.0`. |
| `terms_of_service` | `str` | Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес. |
| `terms_of_service` | `str` | Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес. |
| `contact` | `dict` | Контактная информация для открытого API. Может содержать несколько полей. <details><summary>поля <code>contact</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>Идентификационное имя контактного лица/организации.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>Email адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.</td></tr></tbody></table></details> |
| `contact` | `dict` | Контактная информация для открытого API. Может содержать несколько полей. <details><summary>поля <code>contact</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>Идентификационное имя контактного лица/организации.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>Email адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.</td></tr></tbody></table></details> |
| `license_info` | `dict` | Информация о лицензии открытого API. Может содержать несколько полей. <details><summary>поля <code>license_info</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>ОБЯЗАТЕЛЬНО</strong> (если установлен параметр <code>license_info</code>). Название лицензии, используемой для API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Выражение лицензии <ahref="https://spdx.org/licenses/"class="external-link"target="_blank">SPDX</a> для API. Поле <code>identifier</code> взаимоисключающее с полем <code>url</code>. <small>Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.</td></tr></tbody></table></details> |
| `license_info` | `dict` | Информация о лицензии открытого API. Может содержать несколько полей. <details><summary>поля <code>license_info</code></summary><table><thead><tr><th>Параметр</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>ОБЯЗАТЕЛЬНО</strong> (если установлен параметр <code>license_info</code>). Название лицензии, используемой для API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Выражение лицензии [SPDX](https://spdx.org/licenses/) для API. Поле <code>identifier</code> взаимоисключающее с полем <code>url</code>. <small>Доступно начиная с OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>URL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.</td></tr></tbody></table></details> |
Вы можете задать их следующим образом:
Вы можете задать их следующим образом:
@ -76,7 +76,7 @@
/// info | Дополнительная информация
/// info | Дополнительная информация
Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#tags){.internal-link target=_blank}.
Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#tags).
Если у вас есть зависимости с `yield`, то код выхода (код после `yield`) будет выполняться *после* middleware.
Если у вас есть зависимости с `yield`, то код выхода (код после `yield`) будет выполняться *после* middleware.
Если были какие‑либо фоновые задачи (рассматриваются в разделе [Фоновые задачи](background-tasks.md){.internal-link target=_blank}, вы увидите это позже), они будут запущены *после* всех middleware.
Если были какие‑либо фоновые задачи (рассматриваются в разделе [Фоновые задачи](background-tasks.md), вы увидите это позже), они будут запущены *после* всех middleware.
///
///
@ -35,9 +35,9 @@
/// tip | Совет
/// tip | Совет
Имейте в виду, что можно добавлять проприетарные HTTP-заголовки <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">с префиксом `X-`</a>.
Имейте в виду, что можно добавлять проприетарные HTTP-заголовки [с префиксом `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
Но если вы хотите, чтобы клиент в браузере мог видеть ваши пользовательские заголовки, необходимо добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, описанный в <ahref="https://www.starlette.dev/middleware/#corsmiddleware"class="external-link"target="_blank">документации по CORS Starlette</a>.
Но если вы хотите, чтобы клиент в браузере мог видеть ваши пользовательские заголовки, необходимо добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md)), используя параметр `expose_headers`, описанный в [документации по CORS Starlette](https://www.starlette.dev/middleware/#corsmiddleware).
///
///
@ -61,7 +61,7 @@
/// tip | Совет
/// tip | Совет
Мы используем <ahref="https://docs.python.org/3/library/time.html#time.perf_counter"class="external-link"target="_blank">`time.perf_counter()`</a> вместо `time.time()` для обеспечения большей точности в таких случаях. 🤓
Мы используем [`time.perf_counter()`](https://docs.python.org/3/library/time.html#time.perf_counter) вместо `time.time()` для обеспечения большей точности в таких случаях. 🤓
///
///
@ -90,6 +90,6 @@ app.add_middleware(MiddlewareB)
## Другие middleware { #other-middlewares }
## Другие middleware { #other-middlewares }
О других middleware вы можете узнать больше в разделе [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.
О других middleware вы можете узнать больше в разделе [Расширенное руководство пользователя: Продвинутое middleware](../advanced/middleware.md).
В следующем разделе вы можете прочитать, как настроить <abbrtitle="Cross-Origin Resource Sharing - совместное использование ресурсов между источниками">CORS</abbr> с помощью middleware.
В следующем разделе вы можете прочитать, как настроить <abbrtitle="Cross-Origin Resource Sharing - совместное использование ресурсов между источниками">CORS</abbr> с помощью middleware.
Так как описания обычно длинные и содержат много строк, вы можете объявить описание *операции пути* в <dfntitle="многострочная строка, первое выражение внутри функции (не присвоенное какой-либо переменной), используемая для документации">строке документации</dfn> функции, и **FastAPI** прочитает её оттуда.
Так как описания обычно длинные и содержат много строк, вы можете объявить описание *операции пути* в <dfntitle="многострочная строка, первое выражение внутри функции (не присвоенное какой-либо переменной), используемая для документации">строке документации</dfn> функции, и **FastAPI** прочитает её оттуда.
Вы можете использовать <ahref="https://en.wikipedia.org/wiki/Markdown"class="external-link"target="_blank">Markdown</a> в строке документации, и он будет интерпретирован и отображён корректно (с учетом отступа в строке документации).
Вы можете использовать [Markdown](https://en.wikipedia.org/wiki/Markdown) в строке документации, и он будет интерпретирован и отображён корректно (с учетом отступа в строке документации).
Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать `Annotated`.
Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать `Annotated`.
Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать `Annotated`.
Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions) как минимум до 0.95.1 перед тем, как использовать `Annotated`.
///
///
@ -112,17 +112,17 @@ Python не будет ничего делать с `*`, но он будет з
Валидация также применима к значениям типа `float`.
Валидация также применима к значениям типа `float`.
В этом случае становится важной возможность добавить ограничение <abbrtitle="greater than – больше чем"><code>gt</code></abbr>, вместо <abbrtitle="greater than or equal – больше или равно"><code>ge</code></abbr>, поскольку в таком случае вы можете, например, создать ограничение, чтобы значение было больше `0`, даже если оно меньше `1`.
В этом случае становится важной возможность добавить ограничение <abbrtitle="greater than - больше чем"><code>gt</code></abbr>, вместо <abbrtitle="greater than or equal - больше или равно"><code>ge</code></abbr>, поскольку в таком случае вы можете, например, создать ограничение, чтобы значение было больше `0`, даже если оно меньше `1`.
Таким образом, `0.5` будет корректным значением. А `0.0` или `0` — нет.
Таким образом, `0.5` будет корректным значением. А `0.0` или `0` — нет.
То же самое справедливо и для <abbrtitle="less than – меньше чем"><code>lt</code></abbr>.
То же самое справедливо и для <abbrtitle="less than - меньше чем"><code>lt</code></abbr>.
С помощью `Query`, `Path` (и других классов, которые мы пока не затронули) вы можете добавлять метаданные и строковую валидацию тем же способом, как и в главе [Query-параметры и валидация строк](query-params-str-validations.md){.internal-link target=_blank}.
С помощью `Query`, `Path` (и других классов, которые мы пока не затронули) вы можете добавлять метаданные и строковую валидацию тем же способом, как и в главе [Query-параметры и валидация строк](query-params-str-validations.md).
А также вы можете добавить валидацию числовых данных:
А также вы можете добавить валидацию числовых данных:
Значение параметра пути `item_id` будет передано в функцию в качестве аргумента `item_id`.
Значение параметра пути `item_id` будет передано в функцию в качестве аргумента `item_id`.
Если запустите этот пример и перейдёте по адресу: <ahref="http://127.0.0.1:8000/items/foo"class="external-link"target="_blank">http://127.0.0.1:8000/items/foo</a>, то увидите ответ:
Если запустите этот пример и перейдёте по адресу: [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo), то увидите ответ:
```JSON
```JSON
{"item_id":"foo"}
{"item_id":"foo"}
@ -28,7 +28,7 @@
## <dfntitle="также известно как: сериализация, парсинг, маршаллинг">Преобразование</dfn> данных { #data-conversion }
## <dfntitle="также известно как: сериализация, парсинг, маршаллинг">Преобразование</dfn> данных { #data-conversion }
Если запустите этот пример и перейдёте по адресу: <ahref="http://127.0.0.1:8000/items/3"class="external-link"target="_blank">http://127.0.0.1:8000/items/3</a>, то увидите ответ:
Если запустите этот пример и перейдёте по адресу: [http://127.0.0.1:8000/items/3](http://127.0.0.1:8000/items/3), то увидите ответ:
```JSON
```JSON
{"item_id":3}
{"item_id":3}
@ -44,7 +44,7 @@
## Валидация данных { #data-validation }
## Валидация данных { #data-validation }
Если откроете браузер по адресу <ahref="http://127.0.0.1:8000/items/foo"class="external-link"target="_blank">http://127.0.0.1:8000/items/foo</a>, то увидите интересную HTTP-ошибку:
Если откроете браузер по адресу [http://127.0.0.1:8000/items/foo](http://127.0.0.1:8000/items/foo), то увидите интересную HTTP-ошибку:
```JSON
```JSON
{
{
@ -64,7 +64,7 @@
из-за того, что параметр пути `item_id` имеет значение `"foo"`, которое не является типом `int`.
из-за того, что параметр пути `item_id` имеет значение `"foo"`, которое не является типом `int`.
Та же ошибка возникнет, если вместо `int` передать `float`, например: <ahref="http://127.0.0.1:8000/items/4.2"class="external-link"target="_blank">http://127.0.0.1:8000/items/4.2</a>
Та же ошибка возникнет, если вместо `int` передать `float`, например: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)
/// check | Заметка
/// check | Заметка
@ -78,7 +78,7 @@
## Документация { #documentation }
## Документация { #documentation }
И теперь, когда откроете браузер по адресу: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>, то увидите вот такую автоматически сгенерированную документацию API:
И теперь, когда откроете браузер по адресу: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), то увидите вот такую автоматически сгенерированную документацию API:
Поскольку сгенерированная схема соответствует стандарту <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md"class="external-link"target="_blank">OpenAPI</a>, её можно использовать со множеством совместимых инструментов.
Поскольку сгенерированная схема соответствует стандарту [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md), её можно использовать со множеством совместимых инструментов.
Именно поэтому, **FastAPI** сам предоставляет альтернативную документацию API (используя ReDoc), которую можно получить по адресу: <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
Именно поэтому, **FastAPI** сам предоставляет альтернативную документацию API (используя ReDoc), которую можно получить по адресу: [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc).
<imgsrc="/img/tutorial/path-params/image02.png">
<imgsrc="/img/tutorial/path-params/image02.png">
@ -102,7 +102,7 @@
## Pydantic { #pydantic }
## Pydantic { #pydantic }
Вся проверка данных выполняется под капотом с помощью <ahref="https://docs.pydantic.dev/"class="external-link"target="_blank">Pydantic</a>. Поэтому вы можете быть уверены в качестве обработки данных.
Вся проверка данных выполняется под капотом с помощью [Pydantic](https://docs.pydantic.dev/), поэтому вы получаете все его преимущества. И вы можете быть уверены, что находитесь в надёжных руках.
Вы можете использовать в аннотациях как простые типы данных, вроде `str`, `float`, `bool`, так и более сложные типы.
Вы можете использовать в аннотациях как простые типы данных, вроде `str`, `float`, `bool`, так и более сложные типы.
@ -130,7 +130,7 @@
## Предопределенные значения { #predefined-values }
## Предопределенные значения { #predefined-values }
Что если нам нужно заранее определить допустимые *параметры пути*, которые *операция пути* может принимать? В таком случае можно использовать стандартное перечисление <abbrtitle="Enumeration">`Enum`</abbr> Python.
Что если нам нужно заранее определить допустимые *параметры пути*, которые *операция пути* может принимать? В таком случае можно использовать стандартное перечисление <abbrtitle="Enumeration - Перечисление">`Enum`</abbr> Python.
### Создание класса `Enum` { #create-an-enum-class }
### Создание класса `Enum` { #create-an-enum-class }
Если вы не используете `Annotated`, а применяете **(устаревший) стиль со значением по умолчанию**, то при вызове этой функции без FastAPI в **других местах** вам нужно **помнить** о том, что надо передать аргументы, чтобы всё работало корректно, иначе значения будут не такими, как вы ожидаете (например, вместо `str` будет `QueryInfo` или что-то подобное). И ни редактор, ни Python не будут ругаться при самом вызове функции — ошибка проявится лишь при операциях внутри.
Если вы не используете `Annotated`, а применяете **(устаревший) стиль со значением по умолчанию**, то при вызове этой функции без FastAPI в **других местах** вам нужно **помнить** о том, что надо передать аргументы, чтобы всё работало корректно, иначе значения будут не такими, как вы ожидаете (например, вместо `str` будет `QueryInfo` или что-то подобное). И ни редактор, ни Python не будут ругаться при самом вызове функции — ошибка проявится лишь при операциях внутри.
Так как `Annotated` может содержать больше одной аннотации метаданных, теперь вы можете использовать ту же функцию и с другими инструментами, например с <ahref="https://typer.tiangolo.com/"class="external-link"target="_blank">Typer</a>. 🚀
Так как `Annotated` может содержать больше одной аннотации метаданных, теперь вы можете использовать ту же функцию и с другими инструментами, например с [Typer](https://typer.tiangolo.com/). 🚀
В таких случаях можно использовать **кастомную функцию-валидатор**, которая применяется после обычной валидации (например, после проверки, что значение — это `str`).
В таких случаях можно использовать **кастомную функцию-валидатор**, которая применяется после обычной валидации (например, после проверки, что значение — это `str`).
Этого можно добиться, используя <ahref="https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator"class="external-link"target="_blank">`AfterValidator` Pydantic</a> внутри `Annotated`.
Этого можно добиться, используя [`AfterValidator` Pydantic](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) внутри `Annotated`.
/// tip | Совет
/// tip | Совет
В Pydantic также есть <ahref="https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator"class="external-link"target="_blank">`BeforeValidator`</a> и другие. 🤓
В Pydantic также есть [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) и другие. 🤓
Если вам нужна валидация, требующая общения с каким‑либо **внешним компонентом** — базой данных или другим API — вместо этого используйте **Зависимости FastAPI** (FastAPI Dependencies), вы познакомитесь с ними позже.
Если вам нужна валидация, требующая общения с каким‑либо **внешним компонентом** — базой данных или другим API — вместо этого используйте **Зависимости FastAPI**, вы познакомитесь с ними позже.
Эти кастомные валидаторы предназначены для проверок, которые можно выполнить, имея **только** те же **данные**, что пришли в запросе.
Эти кастомные валидаторы предназначены для проверок, которые можно выполнить, имея **только** те же **данные**, что пришли в запросе.
Чтобы получать загруженные файлы, сначала установите <ahref="https://github.com/Kludex/python-multipart"class="external-link"target="_blank">`python-multipart`</a>.
Чтобы получать загруженные файлы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart).
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например:
```console
```console
$ pip install python-multipart
$ pip install python-multipart
@ -63,8 +63,8 @@ $ pip install python-multipart
* Файл, хранящийся в памяти до максимального предела размера, после преодоления которого он будет храниться на диске.
* Файл, хранящийся в памяти до максимального предела размера, после преодоления которого он будет храниться на диске.
* Это означает, что он будет хорошо работать с большими файлами, такими как изображения, видео, большие бинарные файлы и т.д., не потребляя при этом всю память.
* Это означает, что он будет хорошо работать с большими файлами, такими как изображения, видео, большие бинарные файлы и т.д., не потребляя при этом всю память.
* Из загруженного файла можно получить метаданные.
* Из загруженного файла можно получить метаданные.
* Он реализует <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"class="external-link"target="_blank">file-like</a>`async` интерфейс.
* Он реализует [file-like](https://docs.python.org/3/glossary.html#term-file-like-object)`async` интерфейс.
* Он предоставляет реальный объект Python <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"class="external-link"target="_blank">`SpooledTemporaryFile`</a> который вы можете передать непосредственно другим библиотекам, которые ожидают файл в качестве объекта.
* Он предоставляет реальный объект Python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile), который вы можете передать непосредственно другим библиотекам, которые ожидают файл в качестве объекта.
### `UploadFile` { #uploadfile }
### `UploadFile` { #uploadfile }
@ -72,7 +72,7 @@ $ pip install python-multipart
* `filename`: Строка `str` с исходным именем файла, который был загружен (например, `myimage.jpg`).
* `filename`: Строка `str` с исходным именем файла, который был загружен (например, `myimage.jpg`).
* `content_type`: Строка `str` с типом содержимого (MIME type / media type) (например, `image/jpeg`).
* `content_type`: Строка `str` с типом содержимого (MIME type / media type) (например, `image/jpeg`).
* `file`: <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"class="external-link"target="_blank">`SpooledTemporaryFile`</a> (a <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"class="external-link"target="_blank">file-like</a> объект). Это фактический файл Python, который можно передавать непосредственно другим функциям или библиотекам, ожидающим файл в качестве объекта.
* `file`: [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) (a [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) объект). Это фактический файл Python, который можно передавать непосредственно другим функциям или библиотекам, ожидающим файл в качестве объекта.
`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний `SpooledTemporaryFile`).
`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний `SpooledTemporaryFile`).
@ -120,9 +120,9 @@ contents = myfile.file.read()
Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы.
Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы.
Но когда форма включает файлы, она кодируется как multipart/form-data. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела.
Но когда форма включает файлы, она кодируется как `multipart/form-data`. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела.
Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> web docs for <code>POST</code></a>.
Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке [<abbr title="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> web docs for `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
Чтобы использовать формы, сначала установите <ahref="https://github.com/Kludex/python-multipart"class="external-link"target="_blank">`python-multipart`</a>.
Чтобы использовать формы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart).
Убедитесь, что вы создали и активировали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, а затем установите пакет, например:
Убедитесь, что вы создали и активировали [виртуальное окружение](../virtual-environments.md), а затем установите пакет, например:
Чтобы получать загруженные файлы и/или данные форм, сначала установите <ahref="https://github.com/Kludex/python-multipart"class="external-link"target="_blank">`python-multipart`</a>.
Чтобы получать загруженные файлы и/или данные форм, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart).
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например:
Чтобы использовать формы, сначала установите <ahref="https://github.com/Kludex/python-multipart"class="external-link"target="_blank">`python-multipart`</a>.
Чтобы использовать формы, сначала установите [`python-multipart`](https://github.com/Kludex/python-multipart).
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например:
```console
```console
$ pip install python-multipart
$ pip install python-multipart
@ -56,7 +56,7 @@ $ pip install python-multipart
Но когда форма содержит файлы, она кодируется как `multipart/form-data`. О работе с файлами вы прочтёте в следующей главе.
Но когда форма содержит файлы, она кодируется как `multipart/form-data`. О работе с файлами вы прочтёте в следующей главе.
Если вы хотите узнать больше про эти кодировки и поля формы, обратитесь к <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> веб-документации для `POST`</a>.
Если вы хотите узнать больше про эти кодировки и поля формы, обратитесь к [<abbr title="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> веб-документации для `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
@ -13,6 +13,7 @@ FastAPI будет использовать этот возвращаемый т
* Добавить **JSON Schema** для ответа в OpenAPI *операции пути*.
* Добавить **JSON Schema** для ответа в OpenAPI *операции пути*.
* Это будет использовано **автоматической документацией**.
* Это будет использовано **автоматической документацией**.
* Это также будет использовано инструментами автоматической генерации клиентского кода.
* Это также будет использовано инструментами автоматической генерации клиентского кода.
* **Сериализовать** возвращаемые данные в JSON с помощью Pydantic, который написан на **Rust**, поэтому это будет **намного быстрее**.
Но самое главное:
Но самое главное:
@ -73,9 +74,9 @@ FastAPI будет использовать этот `response_model` для д
/// info | Информация
/// info | Информация
Чтобы использовать `EmailStr`, сначала установите <ahref="https://github.com/JoshData/python-email-validator"class="external-link"target="_blank">`email-validator`</a>.
Чтобы использовать `EmailStr`, сначала установите [`email-validator`](https://github.com/JoshData/python-email-validator).
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установите пакет, например:
Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установите пакет, например:
```console
```console
$ pip install email-validator
$ pip install email-validator
@ -181,7 +182,7 @@ FastAPI делает несколько вещей внутри вместе с
Самый распространённый случай — [возвращать Response напрямую, как описано далее в разделах документации для продвинутых](../advanced/response-directly.md){.internal-link target=_blank}.
Самый распространённый случай — [возвращать Response напрямую, как описано далее в разделах документации для продвинутых](../advanced/response-directly.md).
@ -201,7 +202,7 @@ FastAPI делает несколько вещей внутри вместе с
Но когда вы возвращаете произвольный объект, не являющийся валидным типом Pydantic (например, объект базы данных), и аннотируете его таким образом в функции, FastAPI попытается создать модель ответа Pydantic из этой аннотации типа и потерпит неудачу.
Но когда вы возвращаете произвольный объект, не являющийся валидным типом Pydantic (например, объект базы данных), и аннотируете его таким образом в функции, FastAPI попытается создать модель ответа Pydantic из этой аннотации типа и потерпит неудачу.
То же произойдёт, если у вас будет что-то вроде <dfntitle="Объединение нескольких типов означает «любой из этих типов».">union</dfn> разных типов, где один или несколько не являются валидными типами Pydantic, например, это приведёт к ошибке 💥:
То же произойдёт, если у вас будет что-то вроде <dfntitle="Объединение нескольких типов означает «любой из этих типов».">объединение</dfn> разных типов, где один или несколько не являются валидными типами Pydantic, например, это приведёт к ошибке 💥:
@ -257,7 +258,7 @@ FastAPI делает несколько вещей внутри вместе с
* `response_model_exclude_defaults=True`
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
* `response_model_exclude_none=True`
как описано в <ahref="https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict"class="external-link"target="_blank">документации Pydantic</a> для `exclude_defaults` и `exclude_none`.
как описано в [документации Pydantic](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict) для `exclude_defaults` и `exclude_none`.
В качестве значения параметра `status_code` также может использоваться `IntEnum`, например, из библиотеки <ahref="https://docs.python.org/3/library/http.html#http.HTTPStatus"class="external-link"target="_blank">`http.HTTPStatus`</a> в Python.
В качестве значения параметра `status_code` также может использоваться `IntEnum`, например, из библиотеки [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) в Python.
///
///
@ -66,7 +66,7 @@ FastAPI знает об этом и создаст документацию Open
/// tip | Подсказка
/// tip | Подсказка
Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> документацией об HTTP статус-кодах</a>.
Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с [<abbr title="Mozilla Developer Network - Сеть разработчиков Mozilla">MDN</abbr> документацией об HTTP статус-кодах](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
///
///
@ -98,4 +98,4 @@ FastAPI знает об этом и создаст документацию Open
## Изменение кода статуса по умолчанию { #changing-the-default }
## Изменение кода статуса по умолчанию { #changing-the-default }
Позже, в [Руководстве для продвинутых пользователей](../advanced/response-change-status-code.md){.internal-link target=_blank}, вы узнаете, как возвращать HTTP статус-код, отличный от значения по умолчанию, которое вы объявляете здесь.
Позже, в [Руководстве для продвинутых пользователей](../advanced/response-change-status-code.md), вы узнаете, как возвращать HTTP статус-код, отличный от значения по умолчанию, которое вы объявляете здесь.
Эта дополнительная информация будет добавлена как есть в выходную **JSON Schema** этой модели и будет использоваться в документации API.
Эта дополнительная информация будет добавлена как есть в выходную **JSON Schema** этой модели и будет использоваться в документации API.
Вы можете использовать атрибут `model_config`, который принимает `dict`, как описано в <ahref="https://docs.pydantic.dev/latest/api/config/"class="external-link"target="_blank">Документации Pydantic: Конфигурация</a>.
Вы можете использовать атрибут `model_config`, который принимает `dict`, как описано в [Документация Pydantic: Конфигурация](https://docs.pydantic.dev/latest/api/config/).
Вы можете задать `"json_schema_extra"` с `dict`, содержащим любые дополнительные данные, которые вы хотите видеть в сгенерированной JSON Schema, включая `examples`.
Вы можете задать `"json_schema_extra"` с `dict`, содержащим любые дополнительные данные, которые вы хотите видеть в сгенерированной JSON Schema, включая `examples`.
@ -145,12 +145,12 @@ OpenAPI 3.1.0 (используется начиная с FastAPI 0.99.0) доб
OpenAPI также добавила поля `example` и `examples` в другие части спецификации:
OpenAPI также добавила поля `example` и `examples` в другие части спецификации:
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object"class="external-link"target="_blank">`Parameter Object` (в спецификации)</a>, которое использовалось в FastAPI:
* [`Parameter Object` (в спецификации)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object), которое использовалось в FastAPI:
* `Path()`
* `Path()`
* `Query()`
* `Query()`
* `Header()`
* `Header()`
* `Cookie()`
* `Cookie()`
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object"class="external-link"target="_blank">`Request Body Object`, в поле `content`, в `Media Type Object` (в спецификации)</a>, которое использовалось в FastAPI:
* [`Request Body Object`, в поле `content`, в `Media Type Object` (в спецификации)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object), которое использовалось в FastAPI:
* `Body()`
* `Body()`
* `File()`
* `File()`
* `Form()`
* `Form()`
@ -163,7 +163,7 @@ OpenAPI также добавила поля `example` и `examples` в друг
### Поле `examples` в JSON Schema { #json-schemas-examples-field }
### Поле `examples` в JSON Schema { #json-schemas-examples-field }
Позже в новой версии спецификации JSON Schema было добавлено поле <ahref="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5"class="external-link"target="_blank">`examples`</a>.
Позже в новой версии спецификации JSON Schema было добавлено поле [`examples`](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5).
А затем новый OpenAPI 3.1.0 был основан на последней версии (JSON Schema 2020-12), которая включала это новое поле `examples`.
А затем новый OpenAPI 3.1.0 был основан на последней версии (JSON Schema 2020-12), которая включала это новое поле `examples`.
Пакет <ahref="https://github.com/Kludex/python-multipart"class="external-link"target="_blank">`python-multipart`</a> автоматически устанавливается вместе с **FastAPI**, если вы запускаете команду `pip install "fastapi[standard]"`.
Пакет [`python-multipart`](https://github.com/Kludex/python-multipart) автоматически устанавливается вместе с **FastAPI**, если вы запускаете команду `pip install "fastapi[standard]"`.
Однако, если вы используете команду `pip install fastapi`, пакет `python-multipart` по умолчанию не включается.
Однако, если вы используете команду `pip install fastapi`, пакет `python-multipart` по умолчанию не включается.
Чтобы установить его вручную, убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активировали его и затем установили пакет:
Чтобы установить его вручную, убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активировали его и затем установили пакет:
```console
```console
$ pip install python-multipart
$ pip install python-multipart
@ -45,7 +45,7 @@ $ pip install python-multipart
<divclass="termy">
<divclass="termy">
```console
```console
$ fastapi dev main.py
$ fastapi dev
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
```
@ -54,7 +54,7 @@ $ fastapi dev main.py
## Проверка { #check-it }
## Проверка { #check-it }
Перейдите к интерактивной документации по адресу: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Перейдите к интерактивной документации по адресу: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
Вы увидите примерно следующее:
Вы увидите примерно следующее:
@ -140,7 +140,7 @@ OAuth2 был спроектирован так, чтобы бэкенд или
Поскольку мы используем относительный URL, если ваш API расположен по адресу `https://example.com/`, то он будет ссылаться на `https://example.com/token`. А если ваш API расположен по адресу `https://example.com/api/v1/`, то он будет ссылаться на `https://example.com/api/v1/token`.
Поскольку мы используем относительный URL, если ваш API расположен по адресу `https://example.com/`, то он будет ссылаться на `https://example.com/token`. А если ваш API расположен по адресу `https://example.com/api/v1/`, то он будет ссылаться на `https://example.com/api/v1/token`.
Использование относительного URL важно для того, чтобы ваше приложение продолжало работать даже в таком продвинутом случае, как [За прокси-сервером](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
Использование относительного URL важно для того, чтобы ваше приложение продолжало работать даже в таком продвинутом случае, как [За прокси-сервером](../../advanced/behind-a-proxy.md).
Через неделю срок действия токена истечет, пользователь не будет авторизован и ему придется заново входить в систему, чтобы получить новый токен. А если пользователь (или третье лицо) попытается модифицировать токен, чтобы изменить срок действия, вы сможете это обнаружить, поскольку подписи не будут совпадать.
Через неделю срок действия токена истечет, пользователь не будет авторизован и ему придется заново входить в систему, чтобы получить новый токен. А если пользователь (или третье лицо) попытается модифицировать токен, чтобы изменить срок действия, вы сможете это обнаружить, поскольку подписи не будут совпадать.
Если вы хотите поиграть с JWT-токенами и посмотреть, как они работают, посмотрите <ahref="https://jwt.io/"class="external-link"target="_blank">https://jwt.io</a>.
Если вы хотите поиграть с JWT-токенами и посмотреть, как они работают, посмотрите [https://jwt.io](https://jwt.io/).
## Установка `PyJWT` { #install-pyjwt }
## Установка `PyJWT` { #install-pyjwt }
Нам необходимо установить `pyjwt` для генерации и проверки JWT-токенов на языке Python.
Нам необходимо установить `pyjwt` для генерации и проверки JWT-токенов на языке Python.
Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активируйте его, а затем установите `pyjwt`:
Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активируйте его, а затем установите `pyjwt`:
<divclass="termy">
<divclass="termy">
@ -46,7 +46,7 @@ $ pip install pyjwt
Если вы планируете использовать алгоритмы цифровой подписи, такие как RSA или ECDSA, вам следует установить зависимость библиотеки криптографии `pyjwt[crypto]`.
Если вы планируете использовать алгоритмы цифровой подписи, такие как RSA или ECDSA, вам следует установить зависимость библиотеки криптографии `pyjwt[crypto]`.
Подробнее об этом можно прочитать в <ahref="https://pyjwt.readthedocs.io/en/latest/installation.html"class="external-link"target="_blank">документации по установке PyJWT</a>.
Подробнее об этом можно прочитать в [документации по установке PyJWT](https://pyjwt.readthedocs.io/en/latest/installation.html).
///
///
@ -72,7 +72,7 @@ pwdlib — это отличный пакет Python для работы с хэ
Рекомендуемый алгоритм — "Argon2".
Рекомендуемый алгоритм — "Argon2".
Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активируйте его, и затем установите pwdlib вместе с Argon2:
Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md), активируйте его, и затем установите pwdlib вместе с Argon2:
<divclass="termy">
<divclass="termy">
@ -200,7 +200,7 @@ JWT может использоваться и для других целей,
## Проверка в действии { #check-it }
## Проверка в действии { #check-it }
Запустите сервер и перейдите к документации: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Запустите сервер и перейдите к документации: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
**FastAPI** не требует использовать SQL (реляционную) базу данных. Но вы можете использовать любую базу данных, которую хотите.
**FastAPI** не требует использовать SQL (реляционную) базу данных. Но вы можете использовать любую базу данных, которую хотите.
Здесь мы рассмотрим пример с использованием <ahref="https://sqlmodel.tiangolo.com/"class="external-link"target="_blank">SQLModel</a>.
Здесь мы рассмотрим пример с использованием [SQLModel](https://sqlmodel.tiangolo.com/).
**SQLModel** построен поверх <ahref="https://www.sqlalchemy.org/"class="external-link"target="_blank">SQLAlchemy</a> и Pydantic. Его создал тот же автор, что и **FastAPI**, чтобы он идеально подходил для приложений FastAPI, которым нужны **SQL базы данных**.
**SQLModel** построен поверх [SQLAlchemy](https://www.sqlalchemy.org/) и Pydantic. Его создал тот же автор, что и **FastAPI**, чтобы он идеально подходил для приложений FastAPI, которым нужны **SQL базы данных**.
/// tip | Подсказка
/// tip | Подсказка
@ -26,15 +26,15 @@
/// tip | Подсказка
/// tip | Подсказка
Существует официальный генератор проектов на **FastAPI** и **PostgreSQL**, включающий frontend и другие инструменты: <ahref="https://github.com/fastapi/full-stack-fastapi-template"class="external-link"target="_blank">https://github.com/fastapi/full-stack-fastapi-template</a>
Существует официальный генератор проектов на **FastAPI** и **PostgreSQL**, включающий frontend и другие инструменты: [https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template)
///
///
Это очень простое и короткое руководство. Если вы хотите узнать больше о базах данных в целом, об SQL или о более продвинутых возможностях, обратитесь к <ahref="https://sqlmodel.tiangolo.com/"class="external-link"target="_blank">документации SQLModel</a>.
Это очень простое и короткое руководство. Если вы хотите узнать больше о базах данных в целом, об SQL или о более продвинутых возможностях, обратитесь к [документации SQLModel](https://sqlmodel.tiangolo.com/).
## Установка `SQLModel` { #install-sqlmodel }
## Установка `SQLModel` { #install-sqlmodel }
Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и затем установили `sqlmodel`:
Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md), активировали его и затем установили `sqlmodel`:
Класс `Hero` очень похож на модель Pydantic (фактически, под капотом, *это и есть модель Pydantic*).
Класс `Hero` очень похож на модель Pydantic (фактически, под капотом, это и есть модель Pydantic).
Есть несколько отличий:
Есть несколько отличий:
@ -65,7 +65,7 @@ $ pip install sqlmodel
* `Field(primary_key=True)` сообщает SQLModel, что `id` — это **первичный ключ** в SQL базе данных (подробнее о первичных ключах SQL можно узнать в документации SQLModel).
* `Field(primary_key=True)` сообщает SQLModel, что `id` — это **первичный ключ** в SQL базе данных (подробнее о первичных ключах SQL можно узнать в документации SQLModel).
**Примечание:** Мы используем `int | None` для поля первичного ключа, чтобы в Python-коде можно было *создать объект без `id`* (`id=None`), предполагая, что база данных *сгенерирует его при сохранении*. SQLModel понимает, что база данных предоставит `id`, и *определяет столбец как `INTEGER` (не `NULL`)* в схеме базы данных. См. <ahref="https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id"class="external-link"target="_blank">документацию SQLModel о первичных ключах</a> для подробностей.
**Примечание:** Мы используем `int | None` для поля первичного ключа, чтобы в Python-коде можно было *создать объект без `id`* (`id=None`), предполагая, что база данных *сгенерирует его при сохранении*. SQLModel понимает, что база данных предоставит `id`, и *определяет столбец как `INTEGER` (не `NULL`)* в схеме базы данных. См. [документацию SQLModel о первичных ключах](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id) для подробностей.
* `Field(index=True)` сообщает SQLModel, что нужно создать **SQL индекс** для этого столбца, что позволит быстрее выполнять выборки при чтении данных, отфильтрованных по этому столбцу.
* `Field(index=True)` сообщает SQLModel, что нужно создать **SQL индекс** для этого столбца, что позволит быстрее выполнять выборки при чтении данных, отфильтрованных по этому столбцу.
@ -81,7 +81,7 @@ $ pip install sqlmodel
Параметр `check_same_thread=False` позволяет FastAPI использовать одну и ту же базу данных SQLite в разных потоках. Это необходимо, так как **один запрос** может использовать **больше одного потока** (например, в зависимостях).
Параметр `check_same_thread=False` позволяет FastAPI использовать одну и ту же базу данных SQLite в разных потоках. Это необходимо, так как **один запрос** может использовать **больше одного потока** (например, в зависимостях).
Не волнуйтесь, с такой структурой кода мы позже обеспечим использование **одной *сессии* SQLModel на запрос**, по сути именно этого и добивается `check_same_thread`.
Не волнуйтесь, с такой структурой кода мы позже обеспечим использование **одной сессии SQLModel на запрос**, по сути именно этого и добивается `check_same_thread`.
### Создание таблиц { #create-the-tables }
### Создание таблиц { #create-the-tables }
@ -111,7 +111,7 @@ $ pip install sqlmodel
/// tip | Подсказка
/// tip | Подсказка
В SQLModel появятся утилиты миграций - обёртки над Alembic, но пока вы можете использовать <ahref="https://alembic.sqlalchemy.org/en/latest/"class="external-link"target="_blank">Alembic</a> напрямую.
В SQLModel появятся утилиты миграций — обёртки над Alembic, но пока вы можете использовать [Alembic](https://alembic.sqlalchemy.org/en/latest/) напрямую.
///
///
@ -152,7 +152,7 @@ $ pip install sqlmodel
<divclass="termy">
<divclass="termy">
```console
```console
$ fastapi dev main.py
$ fastapi dev
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
```
@ -337,7 +337,7 @@ $ fastapi dev main.py
<divclass="termy">
<divclass="termy">
```console
```console
$ fastapi dev main.py
$ fastapi dev
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<spanstyle="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
```
@ -352,6 +352,6 @@ $ fastapi dev main.py
## Резюме { #recap }
## Резюме { #recap }
Вы можете использовать <ahref="https://sqlmodel.tiangolo.com/"class="external-link"target="_blank">**SQLModel**</a> для взаимодействия с SQL базой данных и упростить код с помощью *моделей данных* и *моделей-таблиц*.
Вы можете использовать [**SQLModel**](https://sqlmodel.tiangolo.com/) для взаимодействия с SQL базой данных и упростить код с помощью *моделей данных* и *моделей-таблиц*.
Гораздо больше вы можете узнать в документации **SQLModel**, там есть более подробное мини-<ahref="https://sqlmodel.tiangolo.com/tutorial/fastapi/"class="external-link"target="_blank">руководство по использованию SQLModel с **FastAPI**</a>. 🚀
Гораздо больше вы можете узнать в документации **SQLModel**, там есть более подробное мини-[руководство по использованию SQLModel с **FastAPI**](https://sqlmodel.tiangolo.com/tutorial/fastapi/). 🚀
Это отличается от использования `APIRouter`, так как примонтированное приложение является полностью независимым.
Это отличается от использования `APIRouter`, так как примонтированное приложение является полностью независимым.
OpenAPI и документация из вашего главного приложения не будут содержать ничего из примонтированного приложения, и т.д.
OpenAPI и документация из вашего главного приложения не будут содержать ничего из примонтированного приложения, и т.д.
Вы можете прочитать больше об этом в [Расширенном руководстве пользователя](../advanced/index.md){.internal-link target=_blank}.
Вы можете прочитать больше об этом в [Расширенном руководстве пользователя](../advanced/index.md).
## Детали { #details }
## Детали { #details }
@ -38,4 +38,4 @@ OpenAPI и документация из вашего главного прил
## Больше информации { #more-info }
## Больше информации { #more-info }
Для получения дополнительной информации о деталях и настройках ознакомьтесь с <ahref="https://www.starlette.dev/staticfiles/"class="external-link"target="_blank">Документацией Starlette о статических файлах</a>.
Для получения дополнительной информации о деталях и настройках ознакомьтесь с [документацией Starlette о статических файлах](https://www.starlette.dev/staticfiles/).
Благодаря <ahref="https://www.starlette.dev/testclient/"class="external-link"target="_blank">Starlette</a>, тестировать приложения **FastAPI** легко и приятно.
Благодаря [Starlette](https://www.starlette.dev/testclient/), тестировать приложения **FastAPI** легко и приятно.
Тестирование основано на библиотеке <ahref="https://www.python-httpx.org"class="external-link"target="_blank">HTTPX</a>, которая в свою очередь основана на библиотеке Requests, так что все действия знакомы и интуитивно понятны.
Тестирование основано на библиотеке [HTTPX](https://www.python-httpx.org), которая в свою очередь основана на библиотеке Requests, так что все действия знакомы и интуитивно понятны.
Используя эти инструменты, Вы можете напрямую задействовать <ahref="https://docs.pytest.org/"class="external-link"target="_blank">pytest</a> с **FastAPI**.
Используя эти инструменты, Вы можете напрямую задействовать [pytest](https://docs.pytest.org/) с **FastAPI**.
## Использование класса `TestClient` { #using-testclient }
## Использование класса `TestClient` { #using-testclient }
/// info | Информация
/// info | Информация
Для использования класса `TestClient` сначала установите <ahref="https://www.python-httpx.org"class="external-link"target="_blank">`httpx`</a>.
Для использования класса `TestClient` сначала установите [`httpx`](https://www.python-httpx.org).
Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например:
```console
```console
$ pip install httpx
$ pip install httpx
@ -52,7 +52,7 @@ $ pip install httpx
/// tip | Подсказка
/// tip | Подсказка
Если для тестирования Вам, помимо запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, для подключения к базе данных с помощью асинхронного драйвера), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md){.internal-link target=_blank} в расширенном руководстве.
Если для тестирования Вам, помимо запросов к приложению FastAPI, необходимо вызывать асинхронные функции (например, для подключения к базе данных с помощью асинхронного драйвера), то ознакомьтесь со страницей [Асинхронное тестирование](../advanced/async-tests.md) в расширенном руководстве.
Допустим, структура файлов Вашего приложения похожа на ту, что описана на странице [Более крупные приложения](bigger-applications.md){.internal-link target=_blank}:
Допустим, структура файлов Вашего приложения похожа на ту, что описана на странице [Более крупные приложения](bigger-applications.md):
```
```
.
.
@ -80,7 +80,7 @@ $ pip install httpx
### Файл тестов { #testing-file }
### Файл тестов { #testing-file }
Также у Вас может быть файл `test_main.py` содержащий тесты. Можно разместить тестовый файл и файл приложения в одной директории (в директориях для Python-кода желательно размещать и файл`__init__.py`):
Также у Вас может быть файл `test_main.py` содержащий тесты. Он может находиться в том же Python-пакете (в той же директории с файлом`__init__.py`):
``` hl_lines="5"
``` hl_lines="5"
.
.
@ -142,13 +142,13 @@ $ pip install httpx
* Для передачи *HTTP-заголовков*, передайте объект `dict` через параметр `headers`.
* Для передачи *HTTP-заголовков*, передайте объект `dict` через параметр `headers`.
* Для передачи *cookies* также передайте `dict`, но через параметр `cookies`.
* Для передачи *cookies* также передайте `dict`, но через параметр `cookies`.
Для получения дополнительной информации о передаче данных на бэкенд с помощью `httpx` или `TestClient` ознакомьтесь с <ahref="https://www.python-httpx.org"class="external-link"target="_blank">документацией HTTPX</a>.
Для получения дополнительной информации о передаче данных на бэкенд с помощью `httpx` или `TestClient` ознакомьтесь с [документацией HTTPX](https://www.python-httpx.org).
/// info | Информация
/// info | Информация
Обратите внимание, что `TestClient` принимает данные, которые можно конвертировать в JSON, но не модели Pydantic.
Обратите внимание, что `TestClient` принимает данные, которые можно конвертировать в JSON, но не модели Pydantic.
Если в Ваших тестах есть модели Pydantic и Вы хотите отправить их в тестируемое приложение, то можете использовать функцию `jsonable_encoder`, описанную на странице [Кодировщик совместимый с JSON](encoder.md){.internal-link target=_blank}.
Если в Ваших тестах есть модели Pydantic и Вы хотите отправить их в тестируемое приложение, то можете использовать функцию `jsonable_encoder`, описанную на странице [Кодировщик совместимый с JSON](encoder.md).
///
///
@ -156,7 +156,7 @@ $ pip install httpx
Далее Вам нужно установить `pytest`.
Далее Вам нужно установить `pytest`.
Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
Убедитесь, что Вы создали [виртуальное окружение](../virtual-environments.md), активировали его, а затем установили пакет, например:
На этой странице вы узнаете, как пользоваться **виртуальными окружениями** и как они работают.
На этой странице вы узнаете, как пользоваться **виртуальными окружениями** и как они работают.
Если вы готовы начать использовать **инструмент, который управляет всем** за вас (включая установку Python), попробуйте <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">uv</a>.
Если вы готовы начать использовать **инструмент, который управляет всем** за вас (включая установку Python), попробуйте [uv](https://github.com/astral-sh/uv).
///
///
@ -86,7 +86,7 @@ $ python -m venv .venv
//// tab | `uv`
//// tab | `uv`
Если у вас установлен <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">`uv`</a>, вы можете использовать его для создания виртуального окружения.
Если у вас установлен [`uv`](https://github.com/astral-sh/uv), вы можете использовать его для создания виртуального окружения.
<divclass="termy">
<divclass="termy">
@ -150,7 +150,7 @@ $ .venv\Scripts\Activate.ps1
//// tab | Windows Bash
//// tab | Windows Bash
Или если вы используете Bash для Windows (например, <ahref="https://gitforwindows.org/"class="external-link"target="_blank">Git Bash</a>):
Или если вы используете Bash для Windows (например, [Git Bash](https://gitforwindows.org/)):
Если вы используете <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">`uv`</a>, то для установки вы будете использовать его вместо `pip`, поэтому обновлять `pip` не нужно. 😎
Если вы используете [`uv`](https://github.com/astral-sh/uv), то для установки вы будете использовать его вместо `pip`, поэтому обновлять `pip` не нужно. 😎
Если вы использовали <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">`uv`</a> для создания виртуального окружения, он уже сделал это за вас — можно пропустить этот шаг. 😎
Если вы использовали [`uv`](https://github.com/astral-sh/uv) для создания виртуального окружения, он уже сделал это за вас — можно пропустить этот шаг. 😎
Эта команда создаст или изменит некоторые [переменные окружения](environment-variables.md){.internal-link target=_blank}, которые будут доступны для следующих команд.
Эта команда создаст или изменит некоторые [переменные окружения](environment-variables.md), которые будут доступны для следующих команд.
Одна из таких переменных — `PATH`.
Одна из таких переменных — `PATH`.
/// tip | Подсказка
/// tip | Подсказка
Вы можете узнать больше о переменной окружения `PATH` в разделе [Переменные окружения](environment-variables.md#path-environment-variable){.internal-link target=_blank}.
Вы можете узнать больше о переменной окружения `PATH` в разделе [Переменные окружения](environment-variables.md#path-environment-variable).
///
///
@ -846,7 +846,7 @@ I solemnly swear 🐺
Существует много **альтернатив** для управления виртуальными окружениями, зависимостями (requirements), проектами.
Существует много **альтернатив** для управления виртуальными окружениями, зависимостями (requirements), проектами.
Когда вы будете готовы и захотите использовать инструмент для **управления всем проектом** — зависимостями пакетов, виртуальными окружениями и т.п., я бы предложил попробовать <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">uv</a>.
Когда вы будете готовы и захотите использовать инструмент для **управления всем проектом** — зависимостями пакетов, виртуальными окружениями и т.п., я бы предложил попробовать [uv](https://github.com/astral-sh/uv).
Yurii Motov
4 months ago