🌐 Add Russian translation for docs/ru/docs/features.md

docs/ru/docs/features.md

@@ -0,0 +1,206 @@
+# Особенности
+
+## Особенности и возможности FastAPI
+
+**FastAPI** предлагает вам следующее:
+
+### Основан на открытых стандартах
+
+* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> для создания API, включая объявления <abbr title="также известных, как  HTTP-методы, такие, как: POST, GET, PUT, DELETE">операций</abbr> <abbr title="известные как: эндпоинты, маршруты, 'ручки' и т.п.">пути</abbr>, параметров, тела запроса, безопасности и т.д.
+
+
+* Автоматическое документирование моделей данных в соответствии с <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (так как, спецификацмя OpenAPI сама основана на JSON Schema).
+* Разработан, придерживаясь этих стандартов, после тщательного их изучения. Эти стандарты изначально включены во фреймфорк, а не являются дополнительной надстройкой.
+* Это также позволяет использовать автоматическую **генерацию клиентского кода** на многих языках.
+
+### Автоматически генерируемая документация
+
+Интерактивная документация для API и исследования пользовательских веб-интерфейсов. Поскольку этот фреймворк основан на OpenAPI, существует несколько вариантов документирования, 2 из которых включены по умолчанию.
+
+* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>, с интерактивным взаимодействием, вызывает и тестирует ваш API прямо из браузера.
+
+![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)
+
+* Альтернативная документация API в <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>.
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png)
+
+### Только современный Python
+
+Все эти возможности основаны на стандартных **аннотациях типов Python 3.6** (благодаря Pydantic). Не нужно изучать новый синтаксис. Только лишь стандартный современный Python.
+
+Если вам нужно освежить знания, как использовать аннотации типов в Python (даже если вы не используете FastAPI), выделите 2 минуты и просмотрите краткое руководство: [Введение в аннотации типов Python¶
+](python-types.md){.internal-link target=_blank}.
+
+Вы пишете на стандартном Python с аннотациями типов:
+
+```Python
+from datetime import date
+
+from pydantic import BaseModel
+
+# Объявляем параметр user_id с типом `str`
+# и получаем поддержку редактора внутри функции
+def main(user_id: str):
+    return user_id
+
+
+# Модель Pydantic
+class User(BaseModel):
+    id: int
+    name: str
+    joined: date
+```
+
+Это можно использовать так:
+
+```Python
+my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
+
+second_user_data = {
+    "id": 4,
+    "name": "Mary",
+    "joined": "2018-11-30",
+}
+
+my_second_user: User = User(**second_user_data)
+```
+
+!!! Информация
+    `**second_user_data` означает:
+
+    Передать ключи и значения словаря `second_user_data`,  в качестве аргументов типа "ключ-значение", это эквивалентно: `User(id=4, name="Mary", joined="2018-11-30")`.
+
+    (*прим. перев. Для этой операции также используется термин "распаковка".)
+
+### Поддержка редакторов (IDE)
+
+Весь фреймворк был продуман так, чтобы быть простым и интуитивно понятным в использовании, все решения были проверены на множестве редакторов еще до начала разработки, чтобы обеспечить наилучшие условия при написании кода.
+
+В последнем опросе Python-разработчиков было выяснено, <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" class="external-link" target="_blank">что наиболее часто используемой функцией редакторов, является "автодополнение"</a>.
+
+Вся структура **FastAPI** основана на удовлетворении этой возможности. Автодополнение работает везде.
+
+Вам редко нужно будет возвращаться к документации.
+
+Вот как ваш редактор может вам помочь:
+
+* в <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>:
+
+![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png)
+
+* в <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>:
+
+![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png)
+
+Вы будете получать автодополнение кода даже там, где вы считали это невозможным раньше.
+Как пример, ключ `price` внутри тела JSON (который может быть вложенным), приходящего в запросе.
+
+Больше не нужно писать неправильные имена ключей, метаться по документации или прокручивать окно редакторва вверх и вниз, в попытках узнать - использовали вы ранее `username` или `user_name`.
+
+### Краткость
+FastAPI имеет продуманные значения **по умолчанию** для всего, с произвольными настройками везде. Все параметры могут быть тонко подстроены так, чтобы делать то, что вам нужно и определять необходимый вам API.
+
+Но, по умолчанию, всё это **"и так работает"**.
+
+### Проверяет значения
+
+* Проверка значений для большинства (или всех?) **типов данных**  Python, включая:
+    * Объекты JSON (`dict`).
+    * Массивы JSON (`list`) с установленными типами элементов.
+    * Строковые (`str`) поля, с установленными минимальной и максимальной длинами.
+    * Числа (`int`, `float`) с минимальными и максимальными значениями и т.п.
+
+* Проверка для более экзотических типов, таких как:
+    * URL.
+    * Email.
+    * UUID.
+    * ...и другие.
+
+Все проверки обрабатывается хорошо зарекомендовавшим себя и надежным **Pydantic**.
+
+### Безопасность и аутентификация
+
+Встроены функции безопасности и аутентификации. Без каких-либо компромиссов с базами данных или моделями данных.
+
+Все схемы безопасности, определённые в OpenAPI, включая:
+
+* HTTP Basic.
+* **OAuth2** (также с **токенами JWT**). Ознакомьтесь с руководством [OAuth2 с JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
+* Ключи API в:
+    * Заголовках.
+    * Параметрах запросов.
+    * Cookies и т.п.
+
+Вдобавок все функции безопасности от Starlette (включая **сессионные cookies**).
+
+Все инструменты и компоненты построены как многоразовые и легко интегрируются с вашими системами, хранилищами данных, реляционными и NoSQL базами данных и т. д.
+
+### Внедрение зависимостей
+
+FastAPI включает в себя чрезвычайно простую в использовании, но чрезвычайно мощную систему <abbr title='известную как: "components", "resources", "services", "providers"'><strong>Внедрения зависимостей</strong></abbr>.
+
+* Даже зависимости могут иметь зависимости, создавая иерархию или **"графы" зависимостей**.
+* Всё **автоматически обрабатывается** фреймворком.
+* Все зависимости могут запрашивать данные из запросов и **дополнять операции пути** ограничениями и автоматической документацией.
+* **Автоматическая проверка** даже для параметров *операций пути*, определенных в зависимостях.
+* Поддержка сложных систем аутентификации пользователей, **соединений с базами данных** и т.д.
+* **Никаких компромиссов** с базами данных, интерфейсами и т.д. Но легкая интеграция со всеми ними.
+
+### Нет ограничений на "Плагины"
+
+Или, другими словами, нет сложностей с ними, импортируйте и используйте нужный вам код.
+
+Любая интеграция разработана настолько простой в использовании (с зависимостями), что вы можете создать "плагин" для своего приложения в пару строк кода, используя ту же структуру и синтаксис, что и для ваших *операций пути*.
+
+### Проверен
+
+* 100% <abbr title="The amount of code that is automatically tested">покрытие тестами</abbr>.
+* 100% <abbr title="Python type annotations, with this your editor and external tools can give you better support">аннотирование типов</abbr> в кодовой базе.
+* Используется в реально работающих приложениях.
+
+## Особенности и возможности Starlette
+
+**FastAPI** основан на <a href="https://www.starlette.io/" class="external-link" target="_blank"><strong>Starlette</strong></a> и полностью совместим с НИМ. Так что, любой дополнительный код Starlette, который у вас есть, будет также работать.
+
+На самом деле, `FastAPI` - это класс, унаследованный от `Starlette`. Таким образом, если вы уже знаете или используете Starlette, большая часть функционала будет работать так же.
+
+С **FastAPI** вы получаете все возможности **Starlette** (так как FastAPI это всего лишь Starlette на стероидах):
+
+* Серьёзно впечатляющая производительность. Это <a href="https://github.com/encode/starlette#performance" class="external-link" target="_blank">один из самых быстрых и доступных Python-фреймворков, наравне с **NodeJS** и **Go**</a>.
+* Поддержка **WebSocket**.
+* Фоновые задачи для процессов.
+* События запуска и выключения.
+* Тестовый клиент построен на `requests`.
+* **CORS**, GZip, статические файлы, потоковые ответы.
+* Поддержка **сессий и cookie**.
+* 100% покрытие тестами.
+* 100% аннотирование типов в кодовой базе.
+
+## Особенности и возможности Pydantic
+
+**FastAPI** основан на <a href="https://pydantic-docs.helpmanual.io" class="external-link" target="_blank"><strong>Pydantic</strong></a> и полностью совместим с ним. Так что, любой дополнительный код Pydantic, который у вас есть, будет также работать.
+
+Включая внешние библиотеки, также основанные на Pydantic, такие как: <abbr title="Object-Relational Mapper">ORM'ы</abbr>, <abbr title="Object-Document Mapper">ODM'ы</abbr> для баз данных.
+
+Это также означает, что во многих случаях вы можете передавать тот же объект, который получили из запроса, **непосредственно в базу данных**, так как всё проверяется автоматически.
+
+И наоборот, во многих случаях вы можете просто передать объект, полученный из базы данных, **непосредственно клиенту**.
+
+С **FastAPI** вы получаете все возможности **Pydantic** (так как, FastAPI основан на Pydantic, для обработки данных):
+
+* **Никакого мозгоёбства** :
+   (*прим. перев: именно так в оригинале)
+    * Не нужно изучать новых схем в микроязыках.
+    * Если вы знаете аннотации типов в Python, вы знаете, как использовать Pydantic.
+* Развлекайтесь с вашими **<abbr title="Интегрированное окружение для разработки, похожее на текстовый редактор">IDE</abbr>/<abbr title="программа проверяющая ошибки в коде">linter</abbr>/мозгом**:
+    * Структуры данных pydantic - это всего лишь экземпляры классов, определённые вами. Автодополнение, проверка кода, mypy и ваша интуиция - всё будет работать с вашими проверенными данными.
+* **Быстродействие**:
+    * В <a href="https://pydantic-docs.helpmanual.io/benchmarks/" class="external-link" target="_blank">тестовых замерах</a> Pydantic быстрее, чем все другие проверенные библиотеки.
+* Проверка **сложных структур**:
+    * Использование иерархических моделей Pydantic; `List`, `Dict` и т.п. из модуля `typing` (входит в стандартную библиотеку Python).
+    * Валидаторы позволяют четко и легко определять, проверять и документировать сложные схемы данных в виде JSON Schema.
+    * Вы можете иметь глубоко **вложенные объекты JSON** и все они будут проверены и аннотированы.
+* **Расширяемость**:
+    * Pydantic позволяет определять пользовательские типы данных или расширять проверку методами модели, с помощью проверочных декораторов.
+* 100% покрытие тестами.

docs/ru/mkdocs.yml

@@ -37,7 +37,7 @@ plugins:
     data: data
 nav:
 - FastAPI: index.md
-- Languages:
+- Языки:
   - en: /
   - az: /az/
   - de: /de/
@@ -58,6 +58,7 @@ nav:
   - tr: /tr/
   - uk: /uk/
   - zh: /zh/
+- features.md
 - python-types.md
 - Учебник - руководство пользователя:
   - tutorial/background-tasks.md