From: Sebastián Ramírez Date: Sun, 11 Jan 2026 00:15:06 +0000 (-0800) Subject: 🌐 Update translations for uk (update-outdated) (#14587) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6f977366a4154b762f257460b028f44e9686e5a6;p=thirdparty%2Ffastapi%2Ffastapi.git 🌐 Update translations for uk (update-outdated) (#14587) Co-authored-by: github-actions[bot] Co-authored-by: Yurii Motov --- diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 66094c81e4..84255f0f80 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -321,6 +321,8 @@ extra: name: pt - português - link: /ru/ name: ru - русский язык + - link: /uk/ + name: uk - українська мова extra_css: - css/termynal.css - css/custom.css diff --git a/docs/uk/docs/index.md b/docs/uk/docs/index.md index 0811a4c7bb..526409c5cf 100644 --- a/docs/uk/docs/index.md +++ b/docs/uk/docs/index.md @@ -1,8 +1,14 @@ +# FastAPI { #fastapi } + + +

- FastAPI + FastAPI

- Готовий до продакшину, високопродуктивний, простий у вивченні та швидкий для написання коду фреймворк + Фреймворк FastAPI: висока продуктивність, легко вивчати, швидко писати код, готовий до продакшину

@@ -21,46 +27,51 @@ --- -**Документація**: https://fastapi.tiangolo.com +**Документація**: https://fastapi.tiangolo.com -**Програмний код**: https://github.com/fastapi/fastapi +**Вихідний код**: https://github.com/fastapi/fastapi --- -FastAPI - це сучасний, швидкий (високопродуктивний), вебфреймворк для створення API за допомогою Python,в основі якого лежить стандартна анотація типів Python. +FastAPI — це сучасний, швидкий (високопродуктивний) вебфреймворк для створення API за допомогою Python, що базується на стандартних підказках типів Python. Ключові особливості: -* **Швидкий**: Дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших фреймворків](#performance). - -* **Швидке написання коду**: Пришвидшує розробку функціоналу приблизно на 200%-300%. * -* **Менше помилок**: Зменшить кількість помилок спричинених людиною (розробником) на 40%. * -* **Інтуїтивний**: Чудова підтримка редакторами коду. Доповнення всюди. Зменште час на налагодження. -* **Простий**: Спроектований, для легкого використання та навчання. Знадобиться менше часу на читання документації. -* **Короткий**: Зведе до мінімуму дублювання коду. Кожен оголошений параметр може виконувати кілька функцій. -* **Надійний**: Ви матимете стабільний код готовий до продакшину з автоматичною інтерактивною документацією. -* **Стандартизований**: Оснований та повністю сумісний з відкритими стандартами для API: OpenAPI (попередньо відомий як Swagger) та JSON Schema. +* **Швидкий**: дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших Python-фреймворків](#performance). +* **Швидке написання коду**: пришвидшує розробку функціоналу приблизно на 200%–300%. * +* **Менше помилок**: зменшує приблизно на 40% кількість помилок, спричинених людиною (розробником). * +* **Інтуїтивний**: чудова підтримка редакторами коду. Автодоповнення всюди. Менше часу на налагодження. +* **Простий**: спроєктований так, щоб бути простим у використанні та вивченні. Менше часу на читання документації. +* **Короткий**: мінімізує дублювання коду. Кілька можливостей з кожного оголошення параметра. Менше помилок. +* **Надійний**: ви отримуєте код, готовий до продакшину. З автоматичною інтерактивною документацією. +* **Заснований на стандартах**: базується на (і повністю сумісний з) відкритими стандартами для API: OpenAPI (раніше відомий як Swagger) та JSON Schema. -* оцінка на основі тестів внутрішньої команди розробників, створення продуктових застосунків. +* оцінка на основі тестів, проведених внутрішньою командою розробників, що створює продакшн-застосунки. -## Спонсори +## Спонсори { #sponsors } -{% if sponsors %} +### Ключовий спонсор { #keystone-sponsor } + +{% for sponsor in sponsors.keystone -%} + +{% endfor -%} + +### Золоті та срібні спонсори { #gold-and-silver-sponsors } + {% for sponsor in sponsors.gold -%} {% endfor -%} {%- for sponsor in sponsors.silver -%} {% endfor %} -{% endif %} -Other sponsors +Інші спонсори -## Враження +## Враження { #opinions } "_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" @@ -88,7 +99,7 @@ FastAPI - це сучасний, швидкий (високопродуктив "_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" -

Timothy Crosley - Hug creator (ref)
+
Timothy Crosley - Hug creator (ref)
--- @@ -100,50 +111,54 @@ FastAPI - це сучасний, швидкий (високопродуктив --- -## **Typer**, FastAPI CLI +"_If anyone is looking to build a production Python API, I would highly recommend **FastAPI**. It is **beautifully designed**, **simple to use** and **highly scalable**, it has become a **key component** in our API first development strategy and is driving many automations and services such as our Virtual TAC Engineer._" - +
Deon Pillsbury - Cisco (ref)
-Створюючи CLI застосунок для використання в терміналі, замість веб-API зверніть увагу на **Typer**. +--- -**Typer** є молодшим братом FastAPI. І це **FastAPI для CLI**. ⌨️ 🚀 +## Міні-документальний фільм про FastAPI { #fastapi-mini-documentary } -## Вимоги +Наприкінці 2025 року вийшов міні-документальний фільм про FastAPI, ви можете переглянути його онлайн: -FastAPI стоїть на плечах гігантів: +FastAPI Mini Documentary -* Starlette для web частини. -* Pydantic для частини даних. +## **Typer**, FastAPI для CLI { #typer-the-fastapi-of-clis } -## Вставновлення + -
+Якщо ви створюєте застосунок CLI для використання в терміналі замість веб-API, зверніть увагу на **Typer**. -```console -$ pip install fastapi +**Typer** — молодший брат FastAPI. І його задумано як **FastAPI для CLI**. ⌨️ 🚀 ----> 100% -``` +## Вимоги { #requirements } -
+FastAPI стоїть на плечах гігантів: + +* Starlette для вебчастини. +* Pydantic для частини даних. -Вам також знадобиться сервер ASGI для продакшину, наприклад Uvicorn або Hypercorn. +## Встановлення { #installation } + +Створіть і активуйте віртуальне середовище, а потім встановіть FastAPI:
```console -$ pip install uvicorn[standard] +$ pip install "fastapi[standard]" ---> 100% ```
-## Приклад +**Примітка**: переконайтеся, що ви взяли `"fastapi[standard]"` у лапки, щоб це працювало в усіх терміналах. + +## Приклад { #example } -### Створіть +### Створіть { #create-it } -* Створіть файл `main.py` з: +Створіть файл `main.py` з: ```Python from typing import Union @@ -188,22 +203,35 @@ async def read_item(item_id: int, q: Union[str, None] = None): **Примітка**: -Стикнувшись з проблемами, не зайвим буде ознайомитися з розділом _"In a hurry?"_ про `async` та `await` у документації. +Якщо ви не знаєте, перегляньте розділ _"In a hurry?"_ про `async` та `await` у документації. -### Запустіть +### Запустіть { #run-it } -Запустіть server з: +Запустіть сервер за допомогою:
```console -$ uvicorn main:app --reload - +$ fastapi dev main.py + + ╭────────── FastAPI CLI - Development mode ───────────╮ + │ │ + │ Serving at: http://127.0.0.1:8000 │ + │ │ + │ API docs: http://127.0.0.1:8000/docs │ + │ │ + │ Running in development mode, for production use: │ + │ │ + │ fastapi run │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] +INFO: Started reloader process [2248755] using WatchFiles +INFO: Started server process [2248757] INFO: Waiting for application startup. INFO: Application startup complete. ``` @@ -211,21 +239,21 @@ INFO: Application startup complete.
-Про команди uvicorn main:app --reload... +Про команду fastapi dev main.py... + +Команда `fastapi dev` читає ваш файл `main.py`, знаходить у ньому застосунок **FastAPI** і запускає сервер за допомогою Uvicorn. -Команда `uvicorn main:app` посилається на: +За замовчуванням `fastapi dev` запускається з авто-перезавантаженням для локальної розробки. -* `main`: файл `main.py` ("Модуль" Python). -* `app`: об’єкт створений усередині `main.py` рядком `app = FastAPI()`. -* `--reload`: перезапускає сервер після зміни коду. Використовуйте виключно для розробки. +Докладніше читайте в документації FastAPI CLI.
-### Перевірте +### Перевірте { #check-it } -Відкрийте браузер та введіть адресу http://127.0.0.1:8000/items/5?q=somequery. +Відкрийте браузер і перейдіть на http://127.0.0.1:8000/items/5?q=somequery. -Ви побачите у відповідь подібний JSON: +Ви побачите JSON-відповідь: ```JSON {"item_id": 5, "q": "somequery"} @@ -233,32 +261,32 @@ INFO: Application startup complete. Ви вже створили API, який: -* Отримує HTTP запити за _шляхами_ `/` та `/items/{item_id}`. +* Отримує HTTP-запити за _шляхами_ `/` та `/items/{item_id}`. * Обидва _шляхи_ приймають `GET` операції (також відомі як HTTP _методи_). -* _Шлях_ `/items/{item_id}` містить _параметр шляху_ `item_id` який має бути типу `int`. +* _Шлях_ `/items/{item_id}` містить _параметр шляху_ `item_id`, який має бути типу `int`. * _Шлях_ `/items/{item_id}` містить необовʼязковий `str` _параметр запиту_ `q`. -### Інтерактивні документації API +### Інтерактивна документація API { #interactive-api-docs } -Перейдемо сюди http://127.0.0.1:8000/docs. +Тепер перейдіть на http://127.0.0.1:8000/docs. -Ви побачите автоматичну інтерактивну API документацію (створену завдяки Swagger UI): +Ви побачите автоматичну інтерактивну документацію API (надану Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### Альтернативні документації API +### Альтернативна документація API { #alternative-api-docs } -Тепер перейдемо сюди http://127.0.0.1:8000/redoc. +А тепер перейдіть на http://127.0.0.1:8000/redoc. -Ви побачите альтернативну автоматичну документацію (створену завдяки ReDoc): +Ви побачите альтернативну автоматичну документацію (надану ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -## Приклад оновлення +## Приклад оновлення { #example-upgrade } -Тепер модифікуйте файл `main.py`, щоб отримати вміст запиту `PUT`. +Тепер змініть файл `main.py`, щоб отримувати тіло `PUT`-запиту. -Оголошуйте вміст запиту за допомогою стандартних типів Python завдяки Pydantic. +Оголосіть тіло, використовуючи стандартні типи Python, завдяки Pydantic. ```Python hl_lines="4 9-12 25-27" from typing import Union @@ -290,41 +318,41 @@ def update_item(item_id: int, item: Item): return {"item_name": item.name, "item_id": item_id} ``` -Сервер повинен автоматично перезавантажуватися (тому що Ви додали `--reload` до `uvicorn` команди вище). +Сервер `fastapi dev` має автоматично перезавантажитися. -### Оновлення інтерактивної API документації +### Оновлення інтерактивної документації API { #interactive-api-docs-upgrade } -Тепер перейдемо сюди http://127.0.0.1:8000/docs. +Тепер перейдіть на http://127.0.0.1:8000/docs. -* Інтерактивна документація API буде автоматично оновлена, включаючи новий вміст: +* Інтерактивна документація API буде автоматично оновлена, включно з новим тілом: ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* Натисніть кнопку "Try it out", це дозволить вам заповнити параметри та безпосередньо взаємодіяти з API: +* Натисніть кнопку "Try it out", вона дозволяє заповнити параметри та безпосередньо взаємодіяти з API: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) -* Потім натисніть кнопку "Execute", інтерфейс користувача зв'яжеться з вашим API, надішле параметри, у відповідь отримає результати та покаже їх на екрані: +* Потім натисніть кнопку "Execute", інтерфейс користувача зв'яжеться з вашим API, надішле параметри, отримає результати та покаже їх на екрані: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) -### Оновлення альтернативної API документації +### Оновлення альтернативної документації API { #alternative-api-docs-upgrade } -Зараз перейдемо http://127.0.0.1:8000/redoc. +А тепер перейдіть на http://127.0.0.1:8000/redoc. -* Альтернативна документація також показуватиме новий параметр і вміст запиту: +* Альтернативна документація також відобразить новий параметр запиту та тіло: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) -### Підсумки +### Підсумки { #recap } -Таким чином, Ви **один раз** оголошуєте типи параметрів, тіла тощо, як параметри функції. +Отже, ви оголошуєте **один раз** типи параметрів, тіла тощо як параметри функції. Ви робите це за допомогою стандартних сучасних типів Python. Вам не потрібно вивчати новий синтаксис, методи чи класи конкретної бібліотеки тощо. -Використовуючи стандартний **Python**. +Лише стандартний **Python**. Наприклад, для `int`: @@ -332,35 +360,35 @@ def update_item(item_id: int, item: Item): item_id: int ``` -або для більш складної моделі `Item`: +або для складнішої моделі `Item`: ```Python item: Item ``` -...і з цим єдиним оголошенням Ви отримуєте: +...і з цим єдиним оголошенням ви отримуєте: -* Підтримку редактора, включаючи: - * Варіанти заповнення. - * Перевірку типів. -* Перевірку даних: - * Автоматичні та зрозумілі помилки, у разі некоректних даних. - * Перевірка навіть для JSON з високим рівнем вкладеності. -* Перетворення вхідних даних: з мережі до даних і типів Python. Читання з: +* Підтримку редактора, включно з: + * Автодоповненням. + * Перевіркою типів. +* Валідацію даних: + * Автоматичні та зрозумілі помилки, коли дані некоректні. + * Валідацію навіть для глибоко вкладених JSON-обʼєктів. +* Перетворення вхідних даних: з мережі до даних і типів Python. Читання з: * JSON. * Параметрів шляху. * Параметрів запиту. * Cookies. * Headers. * Forms. - * Файлів. -* Перетворення вихідних даних: з типів і даних Python до мережевих даних (як JSON): - * Конвертація Python типів (`str`, `int`, `float`, `bool`, `list`, тощо). - * `datetime` об'єкти. - * `UUID` об'єкти. - * Моделі бази даних. + * Files. +* Перетворення вихідних даних: перетворення з даних і типів Python у мережеві дані (як JSON): + * Перетворення типів Python (`str`, `int`, `float`, `bool`, `list`, тощо). + * Обʼєктів `datetime`. + * Обʼєктів `UUID`. + * Моделей бази даних. * ...та багато іншого. -* Автоматичну інтерактивну документацію API, включаючи 2 альтернативні інтерфейси користувача: +* Автоматичну інтерактивну документацію API, включно з 2 альтернативними інтерфейсами користувача: * Swagger UI. * ReDoc. @@ -368,26 +396,26 @@ item: Item Повертаючись до попереднього прикладу коду, **FastAPI**: -* Підтвердить наявність `item_id` у шляху для запитів `GET` та `PUT`. -* Підтвердить, що `item_id` має тип `int` для запитів `GET` and `PUT`. +* Перевірить, що `item_id` є у шляху для `GET` та `PUT`-запитів. +* Перевірить, що `item_id` має тип `int` для `GET` та `PUT`-запитів. * Якщо це не так, клієнт побачить корисну, зрозумілу помилку. -* Перевірить, чи є необов'язковий параметр запиту з назвою `q` (а саме `http://127.0.0.1:8000/items/foo?q=somequery`) для запитів `GET`. +* Перевірить, чи є необов'язковий параметр запиту з назвою `q` (як у `http://127.0.0.1:8000/items/foo?q=somequery`) для `GET`-запитів. * Оскільки параметр `q` оголошено як `= None`, він необов'язковий. - * За відсутності `None` він був би обов'язковим (як і вміст у випадку з `PUT`). -* Для запитів `PUT` із `/items/{item_id}`, читає вміст як JSON: - * Перевірить, чи має обов'язковий атрибут `name` тип `str`. - * Перевірить, чи має обов'язковий атрибут `price` тип `float`. - * Перевірить, чи існує необов'язковий атрибут `is_offer` та чи має він тип `bool`. - * Усе це також працюватиме для глибоко вкладених об'єктів JSON. -* Автоматично конвертує із та в JSON. -* Документує все за допомогою OpenAPI, який може бути використано в: + * Без `None` він був би обов'язковим (як і тіло у випадку з `PUT`). +* Для `PUT`-запитів до `/items/{item_id}` прочитає тіло як JSON: + * Перевірить, що є обовʼязковий атрибут `name`, який має бути типу `str`. + * Перевірить, що є обовʼязковий атрибут `price`, який має бути типу `float`. + * Перевірить, що є необовʼязковий атрибут `is_offer`, який має бути типу `bool`, якщо він присутній. + * Усе це також працюватиме для глибоко вкладених JSON-обʼєктів. +* Автоматично перетворюватиме з та в JSON. +* Документуватиме все за допомогою OpenAPI, який може бути використано в: * Інтерактивних системах документації. * Системах автоматичної генерації клієнтського коду для багатьох мов. -* Надає безпосередньо 2 вебінтерфейси інтерактивної документації. +* Надаватиме безпосередньо 2 вебінтерфейси інтерактивної документації. --- -Ми лише трішки доторкнулися до коду, але Ви вже маєте уявлення про те, як все працює. +Ми лише трішки доторкнулися до поверхні, але ви вже маєте уявлення про те, як усе працює. Спробуйте змінити рядок: @@ -407,57 +435,131 @@ item: Item ... "item_price": item.price ... ``` -...і побачите, як ваш редактор автоматично заповнюватиме атрибути та знатиме їхні типи: +...і побачите, як ваш редактор автоматично доповнюватиме атрибути та знатиме їхні типи: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) -Для більш повного ознайомлення з додатковими функціями, перегляньте Туторіал - Посібник Користувача. +Для більш повного прикладу, що включає більше можливостей, перегляньте Туторіал — Посібник користувача. -**Spoiler alert**: туторіал - посібник користувача містить: +**Spoiler alert**: туторіал — посібник користувача містить: -* Оголошення **параметрів** з інших місць як: **headers**, **cookies**, **form fields** та **files**. -* Як встановити **перевірку обмежень** як `maximum_length` або `regex`. -* Дуже потужна і проста у використанні система **Ін'єкція Залежностей**. -* Безпека та автентифікація, включаючи підтримку **OAuth2** з **JWT tokens** та **HTTP Basic** автентифікацію. +* Оголошення **параметрів** з інших різних місць, як-от: **headers**, **cookies**, **form fields** та **files**. +* Як встановлювати **обмеження валідації** як `maximum_length` або `regex`. +* Дуже потужну і просту у використанні систему **Dependency Injection**. +* Безпеку та автентифікацію, включно з підтримкою **OAuth2** з **JWT tokens** та **HTTP Basic** auth. * Досконаліші (але однаково прості) техніки для оголошення **глибоко вкладених моделей JSON** (завдяки Pydantic). -* Багато додаткових функцій (завдяки Starlette) як-от: +* Інтеграцію **GraphQL** з Strawberry та іншими бібліотеками. +* Багато додаткових можливостей (завдяки Starlette) як-от: * **WebSockets** * надзвичайно прості тести на основі HTTPX та `pytest` * **CORS** * **Cookie Sessions** * ...та більше. -## Продуктивність +### Розгортання застосунку (необовʼязково) { #deploy-your-app-optional } + +За бажання ви можете розгорнути ваш застосунок FastAPI у FastAPI Cloud, перейдіть і приєднайтеся до списку очікування, якщо ви ще цього не зробили. 🚀 + +Якщо у вас вже є обліковий запис **FastAPI Cloud** (ми запросили вас зі списку очікування 😉), ви можете розгорнути ваш застосунок однією командою. + +Перед розгортанням переконайтеся, що ви ввійшли в систему: + +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +Потім розгорніть ваш застосунок: + +
+ +```console +$ fastapi deploy + +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +Ось і все! Тепер ви можете отримати доступ до вашого застосунку за цією URL-адресою. ✨ + +#### Про FastAPI Cloud { #about-fastapi-cloud } + +**FastAPI Cloud** створено тим самим автором і командою, що стоять за **FastAPI**. + +Він спрощує процес **створення**, **розгортання** та **доступу** до API з мінімальними зусиллями. + +Він забезпечує той самий **developer experience** створення застосунків на FastAPI під час їх **розгортання** у хмарі. 🎉 + +FastAPI Cloud — основний спонсор і джерело фінансування open source проєктів *FastAPI and friends*. ✨ -Незалежні тести TechEmpower показують що застосунки **FastAPI**, які працюють під керуванням Uvicorn є одними з найшвидших серед доступних фреймворків в Python, поступаючись лише Starlette та Uvicorn (які внутрішньо використовуються в FastAPI). (*) +#### Розгортання в інших хмарних провайдерів { #deploy-to-other-cloud-providers } -Щоб дізнатися більше про це, перегляньте розділ Benchmarks. +FastAPI — open source і базується на стандартах. Ви можете розгортати застосунки FastAPI в будь-якому хмарному провайдері, який ви оберете. -## Необов'язкові залежності +Дотримуйтеся інструкцій вашого хмарного провайдера, щоб розгорнути застосунки FastAPI у нього. 🤓 -Pydantic використовує: +## Продуктивність { #performance } + +Незалежні тести TechEmpower показують застосунки **FastAPI**, які працюють під керуванням Uvicorn, як одні з найшвидших доступних Python-фреймворків, поступаючись лише Starlette та Uvicorn (які внутрішньо використовуються в FastAPI). (*) + +Щоб дізнатися більше, перегляньте розділ Benchmarks. + +## Залежності { #dependencies } + +FastAPI залежить від Pydantic і Starlette. + +### Залежності `standard` { #standard-dependencies } + +Коли ви встановлюєте FastAPI за допомогою `pip install "fastapi[standard]"`, ви отримуєте групу необовʼязкових залежностей `standard`: + +Використовується Pydantic: * email-validator - для валідації електронної пошти. -* pydantic-settings - для управління налаштуваннями. -* pydantic-extra-types - для додаткових типів, що можуть бути використані з Pydantic. +Використовується Starlette: + +* httpx - потрібно, якщо ви хочете використовувати `TestClient`. +* jinja2 - потрібно, якщо ви хочете використовувати конфігурацію шаблонів за замовчуванням. +* python-multipart - потрібно, якщо ви хочете підтримувати «parsing» форм за допомогою `request.form()`. -Starlette використовує: +Використовується FastAPI: -* httpx - Необхідно, якщо Ви хочете використовувати `TestClient`. -* jinja2 - Необхідно, якщо Ви хочете використовувати шаблони як конфігурацію за замовчуванням. -* python-multipart - Необхідно, якщо Ви хочете підтримувати "розбір" форми за допомогою `request.form()`. -* itsdangerous - Необхідно для підтримки `SessionMiddleware`. -* pyyaml - Необхідно для підтримки Starlette `SchemaGenerator` (ймовірно, вам це не потрібно з FastAPI). +* uvicorn - для сервера, який завантажує та обслуговує ваш застосунок. Це включає `uvicorn[standard]`, до якого входять деякі залежності (наприклад, `uvloop`), потрібні для високопродуктивної роботи сервера. +* `fastapi-cli[standard]` - щоб надати команду `fastapi`. + * Це включає `fastapi-cloud-cli`, який дозволяє розгортати ваш застосунок FastAPI у FastAPI Cloud. -FastAPI / Starlette використовують: +### Без залежностей `standard` { #without-standard-dependencies } + +Якщо ви не хочете включати необовʼязкові залежності `standard`, ви можете встановити через `pip install fastapi` замість `pip install "fastapi[standard]"`. + +### Без `fastapi-cloud-cli` { #without-fastapi-cloud-cli } + +Якщо ви хочете встановити FastAPI зі стандартними залежностями, але без `fastapi-cloud-cli`, ви можете встановити через `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. + +### Додаткові необовʼязкові залежності { #additional-optional-dependencies } + +Є ще деякі додаткові залежності, які ви можете захотіти встановити. + +Додаткові необовʼязкові залежності Pydantic: + +* pydantic-settings - для керування налаштуваннями. +* pydantic-extra-types - для додаткових типів, що можуть бути використані з Pydantic. -* uvicorn - для сервера, який завантажує та обслуговує вашу програму. -* orjson - Необхідно, якщо Ви хочете використовувати `ORJSONResponse`. -* ujson - Необхідно, якщо Ви хочете використовувати `UJSONResponse`. +Додаткові необовʼязкові залежності FastAPI: -Ви можете встановити все це за допомогою `pip install fastapi[all]`. +* orjson - потрібно, якщо ви хочете використовувати `ORJSONResponse`. +* ujson - потрібно, якщо ви хочете використовувати `UJSONResponse`. -## Ліцензія +## Ліцензія { #license } Цей проєкт ліцензовано згідно з умовами ліцензії MIT. diff --git a/docs/uk/docs/learn/index.md b/docs/uk/docs/learn/index.md index 7f9f21e572..6e28d414ad 100644 --- a/docs/uk/docs/learn/index.md +++ b/docs/uk/docs/learn/index.md @@ -1,5 +1,5 @@ -# Навчання +# Навчання { #learn } -У цьому розділі надані вступні та навчальні матеріали для вивчення FastAPI. +У цьому розділі надані вступні розділи та навчальні матеріали для вивчення **FastAPI**. Це можна розглядати як **книгу**, **курс**, або **офіційний** та рекомендований спосіб освоїти FastAPI. 😎 diff --git a/docs/uk/docs/python-types.md b/docs/uk/docs/python-types.md index 676bafb15c..a82d13a285 100644 --- a/docs/uk/docs/python-types.md +++ b/docs/uk/docs/python-types.md @@ -1,29 +1,28 @@ -# Вступ до типів Python +# Вступ до типів Python { #python-types-intro } -Python підтримує додаткові "підказки типу" ("type hints") (також звані "анотаціями типу" ("type annotations")). +Python підтримує додаткові «підказки типів» (також звані «анотаціями типів»). -Ці **"type hints"** є спеціальним синтаксисом, що дозволяє оголошувати тип змінної. +Ці **«підказки типів»** або анотації — це спеціальний синтаксис, що дозволяє оголошувати тип змінної. -За допомогою оголошення типів для ваших змінних, редактори та інструменти можуть надати вам кращу підтримку. +За допомогою оголошення типів для ваших змінних редактори та інструменти можуть надати вам кращу підтримку. -Це просто **швидкий посібник / нагадування** про анотації типів у Python. Він покриває лише мінімум, необхідний щоб використовувати їх з **FastAPI**... що насправді дуже мало. +Це лише **швидкий туторіал / нагадування** про підказки типів у Python. Він покриває лише мінімум, необхідний щоб використовувати їх з **FastAPI**... що насправді дуже мало. -**FastAPI** повністю базується на цих анотаціях типів, вони дають йому багато переваг. +**FastAPI** повністю базується на цих підказках типів, вони дають йому багато переваг і користі. Але навіть якщо ви ніколи не використаєте **FastAPI**, вам буде корисно дізнатись трохи про них. -/// note +/// note | Примітка -Якщо ви експерт у Python і ви вже знаєте усе про анотації типів - перейдіть до наступного розділу. +Якщо ви експерт у Python і ви вже знаєте все про підказки типів, перейдіть до наступного розділу. /// -## Мотивація +## Мотивація { #motivation } Давайте почнемо з простого прикладу: -{* ../../docs_src/python_types/tutorial001.py *} - +{* ../../docs_src/python_types/tutorial001_py39.py *} Виклик цієї програми виводить: @@ -34,13 +33,12 @@ John Doe Функція виконує наступне: * Бере `first_name` та `last_name`. -* Конвертує кожну літеру кожного слова у верхній регістр за допомогою `title()`. -* Конкатенує їх разом із пробілом по середині. - -{* ../../docs_src/python_types/tutorial001.py hl[2] *} +* Перетворює першу літеру кожного з них у верхній регістр за допомогою `title()`. +* Конкатенує їх разом із пробілом по середині. +{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *} -### Редагуйте це +### Редагуйте це { #edit-it } Це дуже проста програма. @@ -48,11 +46,11 @@ John Doe У певний момент ви розпочали б визначення функції, у вас були б готові параметри... -Але тоді вам потрібно викликати "той метод, який переводить першу літеру у верхній регістр". +Але тоді вам потрібно викликати «той метод, який перетворює першу літеру у верхній регістр». Це буде `upper`? Чи `uppercase`? `first_uppercase`? `capitalize`? -Тоді ви спробуєте давнього друга програміста - автозаповнення редактора коду. +Тоді ви спробуєте давнього друга програміста — автозаповнення редактора коду. Ви надрукуєте перший параметр функції, `first_name`, тоді крапку (`.`), а тоді натиснете `Ctrl+Space`, щоб запустити автозаповнення. @@ -60,7 +58,7 @@ John Doe -### Додайте типи +### Додайте типи { #add-types } Давайте змінимо один рядок з попередньої версії. @@ -78,10 +76,9 @@ John Doe Ось і все. -Це "type hints": - -{* ../../docs_src/python_types/tutorial002.py hl[1] *} +Це «підказки типів»: +{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} Це не те саме, що оголошення значень за замовчуванням, як це було б з: @@ -91,43 +88,41 @@ John Doe Це зовсім інше. -Ми використовуємо двокрапку (`:`), не дорівнює (`=`). +Ми використовуємо двокрапку (`:`), не знак дорівнює (`=`). -І додавання анотації типу зазвичай не змінює того, що сталось би без них. +І додавання підказок типів зазвичай не змінює того, що відбувається, порівняно з тим, що відбувалося б без них. -Але тепер, уявіть що ви посеред процесу створення функції, але з анотаціями типів. +Але тепер уявіть, що ви знову посеред процесу створення функції, але з підказками типів. -В цей же момент, ви спробуєте викликати автозаповнення з допомогою `Ctrl+Space` і побачите: +У той самий момент ви спробуєте викликати автозаповнення за допомогою `Ctrl+Space` і побачите: -Разом з цим, ви можете прокручувати, переглядати опції, допоки ви не знайдете одну, що звучить схоже: +Разом з цим ви можете прокручувати, переглядаючи опції, допоки не знайдете ту, що «щось вам підказує»: -## Більше мотивації - -Перевірте цю функцію, вона вже має анотацію типу: +## Більше мотивації { #more-motivation } -{* ../../docs_src/python_types/tutorial003.py hl[1] *} +Перевірте цю функцію, вона вже має підказки типів: +{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *} Оскільки редактор знає типи змінних, ви не тільки отримаєте автозаповнення, ви також отримаєте перевірку помилок: -Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у строку з допомогою `str(age)`: +Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у рядок за допомогою `str(age)`: -{* ../../docs_src/python_types/tutorial004.py hl[2] *} +{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *} +## Оголошення типів { #declaring-types } -## Оголошення типів - -Щойно ви побачили основне місце для оголошення анотацій типу. Як параметри функції. +Щойно ви побачили основне місце для оголошення підказок типів. Як параметри функції. Це також основне місце, де ви б їх використовували у **FastAPI**. -### Прості типи +### Прості типи { #simple-types } Ви можете оголошувати усі стандартні типи у Python, не тільки `str`. @@ -138,78 +133,51 @@ John Doe * `bool` * `bytes` -{* ../../docs_src/python_types/tutorial005.py hl[1] *} - +{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *} -### Generic-типи з параметрами типів +### Generic-типи з параметрами типів { #generic-types-with-type-parameters } Існують деякі структури даних, які можуть містити інші значення, наприклад `dict`, `list`, `set` та `tuple`. І внутрішні значення також можуть мати свій тип. -Ці типи, які мають внутрішні типи, називаються "**generic**" типами. І оголосити їх можна навіть із внутрішніми типами. +Ці типи, які мають внутрішні типи, називаються «**generic**» типами. І оголосити їх можна навіть із внутрішніми типами. -Щоб оголосити ці типи та внутрішні типи, ви можете використовувати стандартний модуль Python `typing`. Він існує спеціально для підтримки анотацій типів. +Щоб оголосити ці типи та внутрішні типи, ви можете використовувати стандартний модуль Python `typing`. Він існує спеціально для підтримки цих підказок типів. -#### Новіші версії Python +#### Новіші версії Python { #newer-versions-of-python } Синтаксис із використанням `typing` **сумісний** з усіма версіями, від Python 3.6 до останніх, включаючи Python 3.9, Python 3.10 тощо. -У міру розвитку Python **новіші версії** мають покращену підтримку анотацій типів і в багатьох випадках вам навіть не потрібно буде імпортувати та використовувати модуль `typing` для оголошення анотацій типу. - -Якщо ви можете вибрати новішу версію Python для свого проекту, ви зможете скористатися цією додатковою простотою. Дивіться кілька прикладів нижче. - -#### List (список) - -Наприклад, давайте визначимо змінну, яка буде `list` із `str`. - -//// tab | Python 3.8 і вище - -З модуля `typing`, імпортуємо `List` (з великої літери `L`): - -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial006.py!} -``` +У міру розвитку Python **новіші версії** мають покращену підтримку цих анотацій типів і в багатьох випадках вам навіть не потрібно буде імпортувати та використовувати модуль `typing` для оголошення анотацій типів. -Оголосимо змінну з тим самим синтаксисом двокрапки (`:`). +Якщо ви можете вибрати новішу версію Python для свого проекту, ви зможете скористатися цією додатковою простотою. -Як тип вкажемо `List`, який ви імпортували з `typing`. +У всій документації є приклади, сумісні з кожною версією Python (коли є різниця). -Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки: +Наприклад, «**Python 3.6+**» означає, що це сумісно з Python 3.6 або вище (включно з 3.7, 3.8, 3.9, 3.10 тощо). А «**Python 3.9+**» означає, що це сумісно з Python 3.9 або вище (включаючи 3.10 тощо). -```Python hl_lines="4" -{!> ../../docs_src/python_types/tutorial006.py!} -``` +Якщо ви можете використовувати **останні версії Python**, використовуйте приклади для останньої версії — вони матимуть **найкращий і найпростіший синтаксис**, наприклад, «**Python 3.10+**». -//// +#### List { #list } -//// tab | Python 3.9 і вище +Наприклад, давайте визначимо змінну, яка буде `list` із `str`. -Оголосимо змінну з тим самим синтаксисом двокрапки (`:`). +Оголосіть змінну з тим самим синтаксисом двокрапки (`:`). -Як тип вкажемо `list`. +Як тип вкажіть `list`. Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки: -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial006_py39.py!} -``` - -//// +{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *} -/// info +/// info | Інформація -Ці внутрішні типи в квадратних дужках називаються "параметрами типу". +Ці внутрішні типи в квадратних дужках називаються «параметрами типу». -У цьому випадку, `str` це параметр типу переданий у `List` (або `list` у Python 3.9 і вище). +У цьому випадку `str` — це параметр типу, переданий у `list`. /// -Це означає: "змінна `items` це `list`, і кожен з елементів у цьому списку - `str`". - -/// tip - -Якщо ви використовуєте Python 3.9 і вище, вам не потрібно імпортувати `List` з `typing`, ви можете використовувати натомість тип `list`. - -/// +Це означає: «змінна `items` — це `list`, і кожен з елементів у цьому списку — `str`». Зробивши це, ваш редактор може надати підтримку навіть під час обробки елементів зі списку: @@ -221,95 +189,67 @@ John Doe І все ж редактор знає, що це `str`, і надає підтримку для цього. -#### Tuple and Set (кортеж та набір) +#### Tuple and Set { #tuple-and-set } Ви повинні зробити те ж саме, щоб оголосити `tuple` і `set`: -//// tab | Python 3.8 і вище - -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial007.py!} -``` - -//// - -//// tab | Python 3.9 і вище - -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial007_py39.py!} -``` - -//// +{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *} Це означає: -* Змінна `items_t` це `tuple` з 3 елементами, `int`, ще `int`, та `str`. -* Змінна `items_s` це `set`, і кожен його елемент типу `bytes`. +* Змінна `items_t` — це `tuple` з 3 елементами: `int`, ще `int`, та `str`. +* Змінна `items_s` — це `set`, і кожен його елемент має тип `bytes`. -#### Dict (словник) +#### Dict { #dict } Щоб оголосити `dict`, вам потрібно передати 2 параметри типу, розділені комами. -Перший параметр типу для ключа у `dict`. +Перший параметр типу для ключів у `dict`. -Другий параметр типу для значення у `dict`: +Другий параметр типу для значень у `dict`: -//// tab | Python 3.8 і вище - -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial008.py!} -``` - -//// - -//// tab | Python 3.9 і вище - -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial008_py39.py!} -``` - -//// +{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *} Це означає: -* Змінна `prices` це `dict`: - * Ключі цього `dict` типу `str` (наприклад, назва кожного елементу). - * Значення цього `dict` типу `float` (наприклад, ціна кожного елементу). +* Змінна `prices` — це `dict`: + * Ключі цього `dict` мають тип `str` (скажімо, назва кожного елементу). + * Значення цього `dict` мають тип `float` (скажімо, ціна кожного елементу). -#### Union (об'єднання) +#### Union { #union } -Ви можете оголосити, що змінна може бути будь-яким із **кількох типів**, наприклад, `int` або `str`. +Ви можете оголосити, що змінна може бути будь-яким із **кількох типів**, наприклад `int` або `str`. У Python 3.6 і вище (включаючи Python 3.10) ви можете використовувати тип `Union` з `typing` і вставляти в квадратні дужки можливі типи, які можна прийняти. -У Python 3.10 також є **альтернативний синтаксис**, у якому ви можете розділити можливі типи за допомогою вертикальної смуги (`|`). +У Python 3.10 також є **новий синтаксис**, у якому ви можете розділити можливі типи за допомогою вертикальної смуги (`|`). -//// tab | Python 3.8 і вище +//// tab | Python 3.10+ -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial008b.py!} +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial008b_py310.py!} ``` //// -//// tab | Python 3.10 і вище +//// tab | Python 3.9+ -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial008b_py310.py!} +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial008b_py39.py!} ``` //// В обох випадках це означає, що `item` може бути `int` або `str`. -#### Possibly `None` (Optional) +#### Можливо `None` { #possibly-none } Ви можете оголосити, що значення може мати тип, наприклад `str`, але також може бути `None`. У Python 3.6 і вище (включаючи Python 3.10) ви можете оголосити його, імпортувавши та використовуючи `Optional` з модуля `typing`. ```Python hl_lines="1 4" -{!../../docs_src/python_types/tutorial009.py!} +{!../../docs_src/python_types/tutorial009_py39.py!} ``` Використання `Optional[str]` замість просто `str` дозволить редактору допомогти вам виявити помилки, коли ви могли б вважати, що значенням завжди є `str`, хоча насправді воно також може бути `None`. @@ -318,103 +258,128 @@ John Doe Це також означає, що в Python 3.10 ви можете використовувати `Something | None`: -//// tab | Python 3.8 і вище +//// tab | Python 3.10+ -```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial009.py!} +```Python hl_lines="1" +{!> ../../docs_src/python_types/tutorial009_py310.py!} ``` //// -//// tab | Python 3.8 і вище - альтернатива +//// tab | Python 3.9+ ```Python hl_lines="1 4" -{!> ../../docs_src/python_types/tutorial009b.py!} +{!> ../../docs_src/python_types/tutorial009_py39.py!} ``` //// -//// tab | Python 3.10 і вище +//// tab | Python 3.9+ alternative -```Python hl_lines="1" -{!> ../../docs_src/python_types/tutorial009_py310.py!} +```Python hl_lines="1 4" +{!> ../../docs_src/python_types/tutorial009b_py39.py!} ``` //// -#### Generic типи +#### Використання `Union` або `Optional` { #using-union-or-optional } -Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад: +Якщо ви використовуєте версію Python нижче 3.10, ось порада з моєї дуже **суб’єктивної** точки зору: -//// tab | Python 3.8 і вище +* 🚨 Уникайте використання `Optional[SomeType]` +* Натомість ✨ **використовуйте `Union[SomeType, None]`** ✨. -* `List` -* `Tuple` -* `Set` -* `Dict` -* `Union` -* `Optional` -* ...та інші. +Обидва варіанти еквівалентні й «під капотом» це одне й те саме, але я рекомендую `Union` замість `Optional`, тому що слово «**optional**» може створювати враження, ніби значення є необов’язковим, хоча насправді це означає «воно може бути `None`», навіть якщо воно не є необов’язковим і все одно є обов’язковим. -//// +Я вважаю, що `Union[SomeType, None]` більш явно показує, що саме мається на увазі. + +Це лише про слова й назви. Але ці слова можуть впливати на те, як ви та ваша команда думаєте про код. -//// tab | Python 3.9 і вище +Як приклад, розгляньмо цю функцію: -Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині): +{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *} + +Параметр `name` визначено як `Optional[str]`, але він **не є необов’язковим**, ви не можете викликати функцію без параметра: + +```Python +say_hi() # Ой, ні, це викликає помилку! 😱 +``` + +Параметр `name` **все ще є обов’язковим** (не *optional*), тому що він не має значення за замовчуванням. Водночас `name` приймає `None` як значення: + +```Python +say_hi(name=None) # Це працює, None є валідним 🎉 +``` + +Добра новина: щойно ви перейдете на Python 3.10, вам не доведеться про це хвилюватися, адже ви зможете просто використовувати `|` для визначення об’єднань типів: + +{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *} + +І тоді вам не доведеться хвилюватися про назви на кшталт `Optional` і `Union`. 😎 + +#### Generic типи { #generic-types } + +Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад: + +//// tab | Python 3.10+ + +Ви можете використовувати ті самі вбудовані типи як generic (з квадратними дужками та типами всередині): * `list` * `tuple` * `set` * `dict` -І те саме, що й у Python 3.8, із модуля `typing`: +І так само, як і в попередніх версіях Python, з модуля `typing`: * `Union` * `Optional` * ...та інші. +У Python 3.10 як альтернативу використанню generic `Union` та `Optional` ви можете використовувати вертикальну смугу (`|`) для оголошення об’єднань типів — це значно краще й простіше. + //// -//// tab | Python 3.10 і вище +//// tab | Python 3.9+ -Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині): +Ви можете використовувати ті самі вбудовані типи як generic (з квадратними дужками та типами всередині): * `list` * `tuple` * `set` * `dict` -І те саме, що й у Python 3.8, із модуля `typing`: +І generic з модуля `typing`: * `Union` -* `Optional` (так само як у Python 3.8) +* `Optional` * ...та інші. -У Python 3.10, як альтернатива використанню `Union` та `Optional`, ви можете використовувати вертикальну смугу (`|`) щоб оголосити об'єднання типів. - //// -### Класи як типи +### Класи як типи { #classes-as-types } Ви також можете оголосити клас як тип змінної. Скажімо, у вас є клас `Person` з імʼям: -{* ../../docs_src/python_types/tutorial010.py hl[1:3] *} - +{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *} Потім ви можете оголосити змінну типу `Person`: -{* ../../docs_src/python_types/tutorial010.py hl[6] *} - +{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *} І знову ж таки, ви отримуєте всю підтримку редактора: -## Pydantic моделі +Зверніть увагу, що це означає: «`one_person` — це **екземпляр** класу `Person`». -Pydantic це бібліотека Python для валідації даних. +Це не означає: «`one_person` — це **клас** з назвою `Person`». + +## Pydantic моделі { #pydantic-models } + +Pydantic — це бібліотека Python для валідації даних. Ви оголошуєте «форму» даних як класи з атрибутами. @@ -424,47 +389,57 @@ John Doe І ви отримуєте всю підтримку редактора з цим отриманим об’єктом. -Приклад з документації Pydantic: +Приклад з офіційної документації Pydantic: -//// tab | Python 3.8 і вище +{* ../../docs_src/python_types/tutorial011_py310.py *} -```Python -{!> ../../docs_src/python_types/tutorial011.py!} -``` +/// info | Інформація -//// +Щоб дізнатись більше про Pydantic, перегляньте його документацію. -//// tab | Python 3.9 і вище +/// -```Python -{!> ../../docs_src/python_types/tutorial011_py39.py!} -``` +**FastAPI** повністю базується на Pydantic. -//// +Ви побачите набагато більше цього всього на практиці в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. -//// tab | Python 3.10 і вище +/// tip | Порада -```Python -{!> ../../docs_src/python_types/tutorial011_py310.py!} -``` +Pydantic має спеціальну поведінку, коли ви використовуєте `Optional` або `Union[Something, None]` без значення за замовчуванням; детальніше про це можна прочитати в документації Pydantic про Required Optional fields. -//// +/// -/// info +## Підказки типів з анотаціями метаданих { #type-hints-with-metadata-annotations } -Щоб дізнатись більше про Pydantic, перегляньте його документацію. +У Python також є можливість додавати **додаткові метадані** до цих підказок типів за допомогою `Annotated`. -/// +Починаючи з Python 3.9, `Annotated` є частиною стандартної бібліотеки, тож ви можете імпортувати його з `typing`. -**FastAPI** повністю базується на Pydantic. +{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *} -Ви побачите набагато більше цього всього на практиці в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. +Сам Python нічого не робить із цим `Annotated`. А для редакторів та інших інструментів тип усе ще є `str`. + +Але ви можете використати це місце в `Annotated`, щоб надати **FastAPI** додаткові метадані про те, як ви хочете, щоб ваш застосунок поводився. + +Важливо пам’ятати, що **перший *параметр типу***, який ви передаєте в `Annotated`, — це **фактичний тип**. Решта — це лише метадані для інших інструментів. + +Наразі вам просто потрібно знати, що `Annotated` існує і що це стандартний Python. 😎 + +Пізніше ви побачите, наскільки **потужним** це може бути. + +/// tip | Порада + +Той факт, що це **стандартний Python**, означає, що ви й надалі отримуватимете **найкращий можливий досвід розробки** у вашому редакторі, з інструментами, які ви використовуєте для аналізу та рефакторингу коду тощо. ✨ + +А також те, що ваш код буде дуже сумісним із багатьма іншими інструментами та бібліотеками Python. 🚀 + +/// -## Анотації типів у **FastAPI** +## Анотації типів у **FastAPI** { #type-hints-in-fastapi } -**FastAPI** використовує ці підказки для виконання кількох речей. +**FastAPI** використовує ці підказки типів для виконання кількох речей. -З **FastAPI** ви оголошуєте параметри з підказками типу, і отримуєте: +З **FastAPI** ви оголошуєте параметри з підказками типів, і отримуєте: * **Підтримку редактора**. * **Перевірку типів**. @@ -473,17 +448,17 @@ John Doe * **Визначення вимог**: з параметрів шляху запиту, параметрів запиту, заголовків, тіл, залежностей тощо. * **Перетворення даних**: із запиту в необхідний тип. -* **Перевірка даних**: що надходять від кожного запиту: +* **Перевірки даних**: що надходять від кожного запиту: * Генерування **автоматичних помилок**, що повертаються клієнту, коли дані недійсні. * **Документування** API за допомогою OpenAPI: * який потім використовується для автоматичної інтерактивної документації користувальницьких інтерфейсів. -Все це може здатися абстрактним. Не хвилюйтеся. Ви побачите все це в дії в [Туторіал - Посібник користувача](tutorial/index.md){.internal-link target=_blank}. +Все це може здатися абстрактним. Не хвилюйтеся. Ви побачите все це в дії в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}. Важливо те, що за допомогою стандартних типів Python в одному місці (замість того, щоб додавати більше класів, декораторів тощо), **FastAPI** зробить багато роботи за вас. -/// info +/// info | Інформація -Якщо ви вже пройшли весь навчальний посібник і повернулися, щоб дізнатися більше про типи, ось хороший ресурс "шпаргалка" від `mypy`. +Якщо ви вже пройшли весь туторіал і повернулися, щоб дізнатися більше про типи, ось хороший ресурс: «шпаргалка» від `mypy`. /// diff --git a/docs/uk/docs/tutorial/background-tasks.md b/docs/uk/docs/tutorial/background-tasks.md index 0a9349650d..6d7804195e 100644 --- a/docs/uk/docs/tutorial/background-tasks.md +++ b/docs/uk/docs/tutorial/background-tasks.md @@ -1,28 +1,27 @@ -# Фонові задачі +# Фонові задачі { #background-tasks } Ви можете створювати фонові задачі, які будуть виконуватися *після* повернення відповіді. Це корисно для операцій, які потрібно виконати після обробки запиту, але клієнту не обов’язково чекати завершення цієї операції перед отриманням відповіді. -Приклади використання: +Це включає, наприклад: * Надсилання email-сповіщень після виконання певної дії: - * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email відправити у фоні. + * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email-сповіщення надіслати у фоні. * Обробка даних: - * Наприклад, якщо отримано файл, який потрібно обробити довготривалим процесом, можна повернути відповідь "Accepted" ("Прийнято", HTTP 202) і виконати обробку файлу у фоні. + * Наприклад, якщо ви отримали файл, який потрібно обробити довготривалим процесом, можна повернути відповідь «Accepted» (HTTP 202) і виконати обробку файлу у фоні. -## Використання `BackgroundTasks` +## Використання `BackgroundTasks` { #using-backgroundtasks } -Спочатку імпортуйте `BackgroundTasks` і додайте його як параметр у Вашу *функцію операції шляху* (path operation function) до `BackgroundTasks`: +Спочатку імпортуйте `BackgroundTasks` і оголосіть параметр у вашій *функції операції шляху* з анотацією типу `BackgroundTasks`: -{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *} -**FastAPI** автоматично створить об'єкт `BackgroundTasks` і передасть його у цей параметр. +**FastAPI** створить для вас об’єкт типу `BackgroundTasks` і передасть його як цей параметр. +## Створення функції задачі { #create-a-task-function } -## Створення функції задачі - -Створіть функцію, яка буде виконувати фонову задачу. +Створіть функцію, яка буде виконуватися як фонова задача. Це звичайна функція, яка може отримувати параметри. @@ -32,54 +31,54 @@ І оскільки операція запису не використовує `async` та `await`, ми визначаємо функцію як звичайну `def`: -{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *} -## Додавання фонової задачі +## Додавання фонової задачі { #add-the-background-task } -Усередині Вашої *функції обробки шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`: +Усередині вашої *функції операції шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`: -{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} +{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *} `.add_task()` приймає аргументи: -* Функція задача, яка буде виконуватися у фоновому режимі (`write_notification`). Зверніть увагу, що передається обʼєкт без дужок. -* Будь-яка послідовність аргументів, які потрібно передати у функцію завдання у відповідному порядку (`email`). -* Будь-які іменовані аргументи, які потрібно передати у функцію задачу (`message="some notification"`). +* Функцію задачі, яка буде виконуватися у фоновому режимі (`write_notification`). +* Будь-яку послідовність аргументів, які потрібно передати у функцію задачі у відповідному порядку (`email`). +* Будь-які іменовані аргументи, які потрібно передати у функцію задачі (`message="some notification"`). -## Впровадження залежностей +## Впровадження залежностей { #dependency-injection } -Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у під залежності тощо. +Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у підзалежності тощо. -**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту. +**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту: {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} У цьому прикладі повідомлення будуть записані у файл `log.txt` *після* того, як відповідь буде надіслана. -Якщо у запиті був переданий query-параметр, він буде записаний у лог у фоновій задачі. +Якщо у запиті був переданий query, він буде записаний у лог у фоновій задачі. -А потім інша фонова задача, яка створюється у *функції операції шляху*, запише повідомлення з використанням path параметра `email`. +А потім інша фонова задача, згенерована у *функції операції шляху*, запише повідомлення з використанням path параметра `email`. -## Технічні деталі +## Технічні деталі { #technical-details } Клас `BackgroundTasks` походить безпосередньо з `starlette.background`. -Він імпортується безпосередньо у FastAPI, щоб Ви могли використовувати його з `fastapi` і випадково не імпортували `BackgroundTask` (без s в кінці) з `starlette.background`. +Він імпортується/включається безпосередньо у FastAPI, щоб ви могли імпортувати його з `fastapi` і випадково не імпортували альтернативний `BackgroundTask` (без `s` в кінці) з `starlette.background`. Якщо використовувати лише `BackgroundTasks` (а не `BackgroundTask`), то його можна передавати як параметр у *функції операції шляху*, і **FastAPI** подбає про все інше, так само як і про використання об'єкта `Request`. -Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього Вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його. +Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його. -Детальніше можна почитати в офіційній документації Starlette про фонові задачі . +Детальніше можна почитати в офіційній документації Starlette про Background Tasks. -## Застереження +## Застереження { #caveat } -Якщо Вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery. +Якщо вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery. -Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і навіть на кількох серверах. +Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і особливо — на кількох серверах. -Якщо ж Вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI** - програми або виконувати невеликі фонові завдання (наприклад, надсилати сповіщення електронною поштою), достатньо просто використовувати `BackgroundTasks`. +Якщо ж вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI**-програми або виконувати невеликі фонові завдання (наприклад, надсилати email-сповіщення), достатньо просто використовувати `BackgroundTasks`. -## Підсумок +## Підсумок { #recap } -Імпортуйте та використовуйте `BackgroundTasks` як параметр у *функціях операції шляху* та залежностях, щоб додавати фонові задачі. +Імпортуйте та використовуйте `BackgroundTasks` як параметри у *функціях операції шляху* та залежностях, щоб додавати фонові задачі. diff --git a/docs/uk/docs/tutorial/body-fields.md b/docs/uk/docs/tutorial/body-fields.md index 7ddd9d104b..70d94f3d6e 100644 --- a/docs/uk/docs/tutorial/body-fields.md +++ b/docs/uk/docs/tutorial/body-fields.md @@ -1,60 +1,61 @@ -# Тіло - Поля +# Тіло — Поля { #body-fields } -Так само як ви можете визначати додаткову валідацію та метадані у параметрах *функції обробки шляху* за допомогою `Query`, `Path` та `Body`, ви можете визначати валідацію та метадані всередині моделей Pydantic за допомогою `Field` від Pydantic. +Так само як ви можете оголошувати додаткову валідацію та метадані в параметрах *функції операції шляху* за допомогою `Query`, `Path` та `Body`, ви можете оголошувати валідацію та метадані всередині моделей Pydantic, використовуючи `Field` від Pydantic. -## Імпорт `Field` +## Імпорт `Field` { #import-field } Спочатку вам потрібно імпортувати це: {* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *} -/// warning -Зверніть увагу, що `Field` імпортується прямо з `pydantic`, а не з `fastapi`, як всі інші (`Query`, `Path`, `Body` тощо). +/// warning | Попередження + +Зверніть увагу, що `Field` імпортується безпосередньо з `pydantic`, а не з `fastapi`, як усе інше (`Query`, `Path`, `Body` тощо). /// -## Оголошення атрибутів моделі +## Оголошення атрибутів моделі { #declare-model-attributes } -Ви можете використовувати `Field` з атрибутами моделі: +Потім ви можете використовувати `Field` з атрибутами моделі: {* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *} -`Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо. +`Field` працює так само, як `Query`, `Path` і `Body`, має ті самі параметри тощо. /// note | Технічні деталі -Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic. +Насправді `Query`, `Path` та інші, які ви побачите далі, створюють об'єкти підкласів спільного класу `Param`, який сам є підкласом класу `FieldInfo` з Pydantic. І `Field` від Pydantic також повертає екземпляр `FieldInfo`. -`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші підкласи, які ви побачите пізніше, що є підкласами класу Body. +`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші, які ви побачите пізніше, що є підкласами класу `Body`. -Пам'ятайте, що коли ви імпортуєте 'Query', 'Path' та інше з 'fastapi', вони фактично є функціями, які повертають спеціальні класи. +Пам'ятайте, що коли ви імпортуєте `Query`, `Path` та інші з `fastapi`, це фактично функції, які повертають спеціальні класи. /// -/// tip +/// tip | Порада -Зверніть увагу, що кожен атрибут моделі із типом, значенням за замовчуванням та `Field` має ту саму структуру, що й параметр *функції обробки шляху*, з `Field` замість `Path`, `Query` і `Body`. +Зверніть увагу, що кожен атрибут моделі з типом, значенням за замовчуванням і `Field` має ту саму структуру, що й параметр *функції операції шляху*, з `Field` замість `Path`, `Query` і `Body`. /// -## Додавання додаткової інформації +## Додавання додаткової інформації { #add-extra-information } -Ви можете визначити додаткову інформацію у `Field`, `Query`, `Body` тощо. І вона буде включена у згенеровану JSON схему. +Ви можете оголошувати додаткову інформацію в `Field`, `Query`, `Body` тощо. І вона буде включена до згенерованої JSON Schema. -Ви дізнаєтеся більше про додавання додаткової інформації пізніше у документації, коли вивчатимете визначення прикладів. +Ви дізнаєтеся більше про додавання додаткової інформації пізніше в документації, коли вивчатимете, як оголошувати приклади. -/// warning +/// warning | Попередження -Додаткові ключі, передані в `Field`, також будуть присутні у згенерованій схемі OpenAPI для вашого додатка. -Оскільки ці ключі не обов'язково можуть бути частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад, [OpenAPI валідатор](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою. +Додаткові ключі, передані в `Field`, також будуть присутні в отриманій схемі OpenAPI для вашого застосунку. +Оскільки ці ключі не обов'язково є частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад [валідатор OpenAPI](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою. /// -## Підсумок +## Підсумок { #recap } -Ви можете використовувати `Field` з Pydantic для визначення додаткових перевірок та метаданих для атрибутів моделі. +Ви можете використовувати `Field` від Pydantic, щоб оголошувати додаткову валідацію та метадані для атрибутів моделі. -Ви також можете використовувати додаткові іменовані аргументи для передачі додаткових метаданих JSON схеми. +Ви також можете використовувати додаткові keyword arguments, щоб передавати додаткові метадані JSON Schema. diff --git a/docs/uk/docs/tutorial/body-multiple-params.md b/docs/uk/docs/tutorial/body-multiple-params.md index e2acf8a703..dc9a768c35 100644 --- a/docs/uk/docs/tutorial/body-multiple-params.md +++ b/docs/uk/docs/tutorial/body-multiple-params.md @@ -1,24 +1,24 @@ -# Тіло запиту - Декілька параметрів +# Тіло - Декілька параметрів { #body-multiple-parameters } -Тепер, коли ми розглянули використання `Path` та `Query`, розгляньмо більш просунуті способи оголошення тіла запиту в **FastAPI**. +Тепер, коли ми побачили, як використовувати `Path` і `Query`, розгляньмо більш просунуті варіанти оголошення тіла запиту. -## Змішування `Path`, `Query` та параметрів тіла запиту +## Змішування `Path`, `Query` та параметрів тіла { #mix-path-query-and-body-parameters } -По-перше, звісно, Ви можете вільно змішувати оголошення параметрів `Path`, `Query` та тіла запиту, і **FastAPI** правильно їх обробить. +По-перше, звісно, ви можете вільно змішувати оголошення параметрів `Path`, `Query` та тіла запиту, і **FastAPI** знатиме, що робити. -Також Ви можете оголосити параметри тіла як необов’язкові, встановивши для них значення за замовчуванням `None`: +Також ви можете оголошувати параметри тіла як необов’язкові, встановивши для них значення за замовчуванням `None`: {* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *} /// note | Примітка -Зверніть увагу, що в цьому випадку параметр `item`, який береться з тіла запиту, є необов'язковим, оскільки має значення за замовчуванням `None`. +Зверніть увагу, що в цьому випадку параметр `item`, який береться з тіла, є необов'язковим. Оскільки має значення за замовчуванням `None`. /// -## Декілька параметрів тіла запиту +## Декілька параметрів тіла { #multiple-body-parameters } -У попередньому прикладі *операція шляху* очікувала JSON з атрибутами `Item`, наприклад: +У попередньому прикладі *операції шляху* очікували б JSON-тіло з атрибутами `Item`, наприклад: ```JSON { @@ -28,13 +28,15 @@ "tax": 3.2 } ``` -Але Ви також можете оголосити декілька параметрів тіла, наприклад `item` та `user`: + +Але ви також можете оголосити декілька параметрів тіла, наприклад `item` та `user`: {* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *} -У цьому випадку **FastAPI** розпізнає, що є кілька параметрів тіла (два параметри є моделями Pydantic). -Тому він використає назви параметрів як ключі (назви полів) у тілі запиту, очікуючи: +У цьому випадку **FastAPI** помітить, що у функції є більше ніж один параметр тіла (є два параметри, які є моделями Pydantic). + +Тож він використає назви параметрів як ключі (назви полів) у тілі та очікуватиме тіло такого вигляду: ```JSON { @@ -53,27 +55,28 @@ /// note | Примітка -Зверніть увагу, що хоча `item` оголошено, так само як і раніше, тепер він очікується в тілі під ключем `item`. +Зверніть увагу, що хоча `item` оголошено так само, як і раніше, тепер він очікується всередині тіла з ключем `item`. /// -**FastAPI** автоматично конвертує дані із запиту таким чином, щоб параметр `item` отримав свій вміст, і те ж саме стосується `user`. +**FastAPI** виконає автоматичне перетворення із запиту, щоб параметр `item` отримав свій конкретний вміст, і те ж саме для `user`. -Він виконає валідацію складених даних і задокументує їх відповідним чином у схемі OpenAPI та в автоматичній документації. +Він виконає валідацію складених даних і задокументує це таким чином у схемі OpenAPI та в автоматичній документації. -## Одиничні значення в тілі запиту +## Одиничні значення в тілі { #singular-values-in-body } Так само як є `Query` і `Path` для визначення додаткових даних для параметрів запиту та шляху, **FastAPI** надає еквівалентний `Body`. -Наприклад, розширюючи попередню модель, Ви можете вирішити додати ще один ключ `importance` в те ж саме тіло запиту разом із `item` і `user`. +Наприклад, розширивши попередню модель, ви можете вирішити додати ще один ключ `importance` у те саме тіло, окрім `item` і `user`. -Якщо Ви оголосите його як є, то, оскільки це одиничне значення, **FastAPI** припускатиме, що це параметр запиту (query parameter). +Якщо оголосити його як є, оскільки це одиничне значення, **FastAPI** припустить, що це параметр запиту. -Але Ви можете вказати **FastAPI** обробляти його як інший ключ тіла (body key), використовуючи `Body`: +Але ви можете вказати **FastAPI** обробляти його як інший ключ тіла, використовуючи `Body`: {* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *} -У цьому випадку **FastAPI** очікуватиме тіло запиту у такому вигляді: + +У цьому випадку **FastAPI** очікуватиме тіло такого вигляду: ```JSON { @@ -90,19 +93,20 @@ "importance": 5 } ``` -Знову ж таки, **FastAPI** конвертуватиме типи даних, перевірятиме їх, створюватиме документацію тощо. -## Декілька body та query параметрів +Знову ж таки, він перетворюватиме типи даних, перевірятиме, документуватиме тощо. -Звісно, Ви можете оголошувати додаткові query параметри запиту, коли це необхідно, на додаток до будь-яких параметрів тіла запиту. +## Декілька параметрів тіла та query { #multiple-body-params-and-query } -Оскільки за замовчуванням окремі значення інтерпретуються як параметри запиту, Вам не потрібно явно додавати `Query`, можна просто використати: +Звісно, ви також можете оголошувати додаткові query параметри щоразу, коли це потрібно, додатково до будь-яких параметрів тіла. + +Оскільки за замовчуванням одиничні значення інтерпретуються як параметри запиту, вам не потрібно явно додавати `Query`, ви можете просто зробити: ```Python q: Union[str, None] = None ``` -Або в Python 3.10 та вище: +Або в Python 3.10 і вище: ```Python q: str | None = None @@ -115,17 +119,17 @@ q: str | None = None /// info | Інформація -`Body` також має ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які Ви побачите пізніше. +`Body` також має всі ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які ви побачите пізніше. /// -## Вкладений поодинокий параметр тіла запиту +## Вбудувати один параметр тіла { #embed-a-single-body-parameter } -Припустимо, у вас є лише один параметр тіла запиту `item` з моделі Pydantic `Item`. +Скажімо, у вас є лише один параметр тіла `item` з моделі Pydantic `Item`. -За замовчуванням **FastAPI** очікуватиме, що тіло запиту міститиме вміст безпосередньо. +За замовчуванням **FastAPI** очікуватиме його тіло безпосередньо. -Але якщо Ви хочете, щоб він очікував JSON з ключем `item`, а всередині — вміст моделі (так, як це відбувається при оголошенні додаткових параметрів тіла), Ви можете використати спеціальний параметр `Body` — `embed`: +Але якщо ви хочете, щоб він очікував JSON з ключем `item`, а всередині нього — вміст моделі, як це відбувається, коли ви оголошуєте додаткові параметри тіла, ви можете використати спеціальний параметр `Body` — `embed`: ```Python item: Item = Body(embed=True) @@ -135,7 +139,8 @@ item: Item = Body(embed=True) {* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *} -У цьому випадку **FastAPI** очікуватиме тіло запиту такого вигляду: + +У цьому випадку **FastAPI** очікуватиме тіло такого вигляду: ```JSON hl_lines="2" { @@ -159,12 +164,12 @@ item: Item = Body(embed=True) } ``` -## Підсумок +## Підсумок { #recap } -Ви можете додавати кілька параметрів тіла до Вашої *функції операції шляху* (*path operation function*), навіть якщо запит може мати лише одне тіло. +Ви можете додавати кілька параметрів тіла до вашої *функції операції шляху*, навіть якщо запит може мати лише одне тіло. -Але **FastAPI** обробить це, надасть Вам потрібні дані у функції, перевірить їх та задокументує коректну схему в *операції шляху*. +Але **FastAPI** обробить це, надасть вам правильні дані у функції та перевірить і задокументує правильну схему в *операції шляху*. -Також Ви можете оголошувати окремі значення, які будуть отримані як частина тіла запиту. +Також ви можете оголошувати одиничні значення, щоб отримувати їх як частину тіла. -Крім того, Ви можете вказати **FastAPI** вбудовувати тіло в ключ, навіть якщо оголошено лише один параметр. +І ви можете вказати **FastAPI** вбудовувати тіло в ключ, навіть коли оголошено лише один параметр. diff --git a/docs/uk/docs/tutorial/body-nested-models.md b/docs/uk/docs/tutorial/body-nested-models.md index abc33f2eb3..6d0669358a 100644 --- a/docs/uk/docs/tutorial/body-nested-models.md +++ b/docs/uk/docs/tutorial/body-nested-models.md @@ -1,8 +1,8 @@ -# Тіло запиту - Вкладені моделі +# Тіло - Вкладені моделі { #body-nested-models } -З **FastAPI** Ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic). +З **FastAPI** ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic). -## Поля списку +## Поля списку { #list-fields } Ви можете визначити атрибут як підтип. Наприклад, Python-список (`list`): @@ -10,47 +10,28 @@ Це зробить `tags` списком, хоча не визначається тип елементів списку. -## Поля списку з параметром типу +## Поля списку з параметром типу { #list-fields-with-type-parameter } -Але Python має специфічний спосіб оголошення списків з внутрішніми типами або "параметрами типу": -### Імпортуємо `List` з модуля typing +Але Python має специфічний спосіб оголошення списків з внутрішніми типами або «параметрами типу»: -У Python 3.9 і вище можна використовувати стандартний `list` для оголошення таких типів, як ми побачимо нижче. 💡 +### Оголошення `list` з параметром типу { #declare-a-list-with-a-type-parameter } -Але в Python версії до 3.9 (від 3.6 і вище) спочатку потрібно імпортувати `List` з модуля стандартної бібліотеки Python `typing`: - -{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *} - -### Оголошення `list` з параметром типу - -Щоб оголосити типи з параметрами типу (внутрішніми типами), такими як `list`, `dict`, `tuple`: - -* Якщо Ви використовуєте версію Python до 3.9, імпортуйте їх відповідну версію з модуля `typing`. -* Передайте внутрішні типи як "параметри типу", використовуючи квадратні дужки: `[` and `]`. - -У Python 3.9 це буде виглядати так: +Щоб оголосити типи з параметрами типу (внутрішніми типами), такими як `list`, `dict`, `tuple`, +передайте внутрішні тип(и) як «параметри типу», використовуючи квадратні дужки: `[` and `]` ```Python my_list: list[str] ``` -У версіях Python до 3.9 це виглядає так: - -```Python -from typing import List - -my_list: List[str] -``` - Це стандартний синтаксис Python для оголошення типів. Використовуйте той самий стандартний синтаксис для атрибутів моделей з внутрішніми типами. -Отже, у нашому прикладі, ми можемо зробити `tags` саме "списком рядків": +Отже, у нашому прикладі, ми можемо зробити `tags` саме «списком рядків»: {* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *} -## Типи множин +## Типи множин { #set-types } Але потім ми подумали, що теги не повинні повторюватися, вони, ймовірно, повинні бути унікальними рядками. @@ -60,29 +41,29 @@ my_list: List[str] {* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *} -Навіть якщо Ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів. +Навіть якщо ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів. -І коли Ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів. +І коли ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів. І це буде анотовано/документовано відповідно. -## Вкладені моделі +## Вкладені моделі { #nested-models } Кожен атрибут моделі Pydantic має тип. Але цей тип сам може бути іншою моделлю Pydantic. -Отже, Ви можете оголосити глибоко вкладені JSON "об'єкти" з конкретними іменами атрибутів, типами та перевірками. +Отже, ви можете оголосити глибоко вкладені JSON «об'єкти» з конкретними іменами атрибутів, типами та перевірками. Усе це, вкладене без обмежень. -### Визначення підмоделі +### Визначення підмоделі { #define-a-submodel } Наприклад, ми можемо визначити модель `Image`: {* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *} -### Використання підмоделі як типу +### Використання підмоделі як типу { #use-the-submodel-as-a-type } А потім ми можемо використовувати її як тип атрибута: @@ -104,16 +85,16 @@ my_list: List[str] } ``` -Завдяки такій декларації у **FastAPI** Ви отримуєте: +Завдяки такій декларації у **FastAPI** ви отримуєте: * Підтримку в редакторі (автозавершення тощо), навіть для вкладених моделей * Конвертацію даних * Валідацію даних * Автоматичну документацію -## Спеціальні типи та валідація +## Спеціальні типи та валідація { #special-types-and-validation } -Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. Ви можете використовувати складніші типи, які наслідують `str`. +Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. ви можете використовувати складніші типи, які наслідують `str`. Щоб побачити всі доступні варіанти, ознайомтеся з оглядом типів у Pydantic. Деякі приклади будуть у наступних розділах. @@ -123,9 +104,9 @@ my_list: List[str] Рядок буде перевірено як дійсну URL-адресу і задокументовано в JSON Schema / OpenAPI як URL. -## Атрибути зі списками підмоделей +## Атрибути зі списками підмоделей { #attributes-with-lists-of-submodels } -У Pydantic Ви можете використовувати моделі як підтипи для `list`, `set` тощо: +У Pydantic ви можете використовувати моделі як підтипи для `list`, `set` тощо: {* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *} @@ -161,7 +142,7 @@ my_list: List[str] /// -## Глибоко вкладені моделі +## Глибоко вкладені моделі { #deeply-nested-models } Ви можете визначати вкладені моделі довільної глибини: @@ -173,14 +154,9 @@ my_list: List[str] /// -## Тіла запитів, що складаються зі списків +## Тіла запитів, що складаються зі списків { #bodies-of-pure-lists } -Якщо верхній рівень JSON тіла, яке Ви очікуєте, є JSON `масивом` (у Python — `list`), Ви можете оголосити тип у параметрі функції, як і в моделях Pydantic: - -```Python -images: List[Image] -``` -або в Python 3.9 і вище: +Якщо верхній рівень JSON тіла, яке ви очікуєте, є JSON `масивом` (у Python — `list`), ви можете оголосити тип у параметрі функції, як і в моделях Pydantic: ```Python images: list[Image] @@ -190,7 +166,7 @@ images: list[Image] {* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *} -## Підтримка в редакторі всюди +## Підтримка в редакторі всюди { #editor-support-everywhere } Ви отримаєте підтримку в редакторі всюди. @@ -200,23 +176,23 @@ images: list[Image] Ви не змогли б отримати таку підтримку в редакторі, якби працювали напряму зі `dict`, а не з моделями Pydantic. -Але Вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON. +Але вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON. -## Тіла з довільними `dict` +## Тіла з довільними `dict` { #bodies-of-arbitrary-dicts } Ви також можете оголосити тіло як `dict` з ключами одного типу та значеннями іншого типу. -Це корисно, якщо Ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic). +Це корисно, якщо ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic). -Це буде корисно, якщо Ви хочете приймати ключі, які заздалегідь невідомі. +Це буде корисно, якщо ви хочете приймати ключі, які заздалегідь невідомі. --- -Це також зручно, якщо Ви хочете мати ключі іншого типу (наприклад, `int`). +Це також зручно, якщо ви хочете мати ключі іншого типу (наприклад, `int`). Ось що ми розглянемо далі. -У цьому випадку Ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`: +У цьому випадку ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`: {* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *} @@ -228,18 +204,18 @@ images: list[Image] Це означає, що навіть якщо клієнти вашого API надсилатимуть ключі у вигляді рядків, якщо вони містять цілі числа, Pydantic конвертує їх і проведе валідацію. -Тобто `dict`, який Ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`. +Тобто `dict`, який ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`. /// -## Підсумок +## Підсумок { #recap } -З **FastAPI** Ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним. +З **FastAPI** ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним. А також отримуєте всі переваги: * Підтримка в редакторі (автодоповнення всюди!) * Конвертація даних (парсинг/сериалізація) -* Валідація даних +* Валідацію даних * Документація схем * Автоматичне створення документації diff --git a/docs/uk/docs/tutorial/body-updates.md b/docs/uk/docs/tutorial/body-updates.md index e78b5a5bf3..2ae68291ca 100644 --- a/docs/uk/docs/tutorial/body-updates.md +++ b/docs/uk/docs/tutorial/body-updates.md @@ -1,8 +1,8 @@ -# Тіло – Оновлення +# Тіло — Оновлення { #body-updates } -## Оновлення з використанням `PUT` +## Оновлення із заміною за допомогою `PUT` { #update-replacing-with-put } -Щоб оновити елемент, Ви можете використати HTTP `PUT` операцію. +Щоб оновити елемент, ви можете використати HTTP `PUT` операцію. Ви можете використати `jsonable_encoder`, щоб перетворити вхідні дані на такі, які можна зберігати як JSON (наприклад, у NoSQL базі даних). Наприклад, перетворюючи `datetime` у `str`. @@ -10,7 +10,7 @@ `PUT` використовується для отримання даних, які мають замінити чинні дані. -### Попередження про заміну +### Попередження про заміну { #warning-about-replacing } Це означає, що якщо Ви хочете оновити елемент `bar`, використовуючи `PUT` з тілом: @@ -26,7 +26,7 @@ І дані будуть збережені з цим "новим" значенням `tax` = `10.5`. -## Часткові оновлення з `PATCH` +## Часткові оновлення з `PATCH` { #partial-updates-with-patch } Ви також можете використовувати операцію HTTP `PATCH` для *часткового* оновлення даних. @@ -34,53 +34,37 @@ /// note | Примітка -`PATCH` менш відомий і рідше використовується, ніж `PUT`. +`PATCH` менш поширений і менш відомий, ніж `PUT`. І багато команд використовують лише `PUT`, навіть для часткових оновлень. -Ви **вільні** використовувати їх так, як хочете, **FastAPI** не накладає обмежень. +Ви **вільні** використовувати їх так, як хочете, **FastAPI** не накладає жодних обмежень. -Але цей посібник показує Вам більш-менш як їх задумано використовувати. +Але цей посібник показує вам, більш-менш, як їх задумано використовувати. /// -### Використання параметра `exclude_unset` у Pydantic +### Використання параметра `exclude_unset` у Pydantic { #using-pydantics-exclude-unset-parameter } -Якщо Ви хочете отримати часткові оновлення, дуже зручно використовувати параметр `exclude_unset` у методі `.model_dump()` моделі Pydantic. +Якщо Ви хочете отримувати часткові оновлення, дуже корисно використовувати параметр `exclude_unset` у `.model_dump()` моделі Pydantic. Наприклад: `item.model_dump(exclude_unset=True)`. -/// info | Інформація +Це згенерує `dict` лише з тими даними, які були встановлені під час створення моделі `item`, виключаючи значення за замовчуванням. -У Pydantic v1 цей метод називався `.dict()`, він був застарілий (але все ще підтримується) у Pydantic v2, і був перейменований у `.model_dump()`. - -Приклади тут використовують `.dict()` для сумісності з Pydantic v1, але Вам слід використовувати `.model_dump()`, якщо можете використовувати Pydantic v2. - -/// - -Це створить `dict` лише з тими даними, які були явно встановлені під час створення моделі `item`, виключаючи значення за замовчуванням. - -Тоді Ви можете використовувати це, щоб створити `dict` лише з даними, які були встановлені (надіслані у запиті), пропускаючи значення за замовчуванням: +Тоді Ви можете використовувати це, щоб згенерувати `dict` лише з даними, які були встановлені (надіслані у запиті), пропускаючи значення за замовчуванням: {* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *} -### Використання параметра `update` у Pydantic +### Використання параметра `update` у Pydantic { #using-pydantics-update-parameter } -Тепер Ви можете створити копію наявної моделі за допомогою `.model_copy()`, і передати параметр `update` з `dict` , який містить дані для оновлення. - -/// info | Інформація - -У Pydantic v1 метод називався `.copy()`, він був застарілий (але все ще підтримується) у Pydantic v2, і був перейменований у `.model_copy()`. - -Приклади тут використовують `.copy()` для сумісності з Pydantic v1, але якщо Ви можете використовувати Pydantic v2 — Вам слід використовувати `.model_copy()` замість цього. - -/// +Тепер Ви можете створити копію наявної моделі за допомогою `.model_copy()`, і передати параметр `update` з `dict`, який містить дані для оновлення. Наприклад: `stored_item_model.model_copy(update=update_data)`: {* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *} -### Підсумок часткових оновлень +### Підсумок часткових оновлень { #partial-updates-recap } У підсумку, щоб застосувати часткові оновлення, Ви: @@ -101,7 +85,7 @@ Насправді Ви можете використовувати цю саму техніку і з операцією HTTP `PUT`. -Але приклад тут використовує `PATCH`, тому що він був створений саме для таких випадків. +Але приклад тут використовує `PATCH`, тому що він був створений для таких випадків. /// @@ -109,7 +93,7 @@ Зверніть увагу, що модель запиту все ще проходить валідацію. -Тож, якщо Ви хочете отримувати часткові оновлення, які можуть не містити жодного атрибута, Вам потрібно мати модель, де всі атрибути позначені як необов’язкові (зі значеннями за замовчуванням або `None`). +Тож, якщо Ви хочете отримувати часткові оновлення, які можуть пропускати всі атрибути, Вам потрібно мати модель, де всі атрибути позначені як необов’язкові (зі значеннями за замовчуванням або `None`). Щоб розрізняти моделі з усіма необов’язковими значеннями для **оновлення** і моделі з обов’язковими значеннями для **створення**, Ви можете скористатись ідеями, описаними у [Додаткові моделі](extra-models.md){.internal-link target=_blank}. diff --git a/docs/uk/docs/tutorial/body.md b/docs/uk/docs/tutorial/body.md index 38fed7bb8d..ca1f308ab5 100644 --- a/docs/uk/docs/tutorial/body.md +++ b/docs/uk/docs/tutorial/body.md @@ -1,14 +1,14 @@ -# Тіло запиту +# Тіло запиту { #request-body } Коли вам потрібно надіслати дані з клієнта (скажімо, браузера) до вашого API, ви надсилаєте їх як **тіло запиту**. Тіло **запиту** — це дані, надіслані клієнтом до вашого API. Тіло **відповіді** — це дані, які ваш API надсилає клієнту. -Ваш API майже завжди має надсилати тіло **відповіді**. Але клієнтам не обов’язково потрібно постійно надсилати тіла **запитів**. +Ваш API майже завжди має надсилати тіло **відповіді**. Але клієнтам не обов’язково потрібно постійно надсилати тіла **запитів** — інколи вони лише запитують шлях, можливо з деякими параметрами запиту, але не надсилають тіло. Щоб оголосити тіло **запиту**, ви використовуєте Pydantic моделі з усією їх потужністю та перевагами. -/// info +/// info | Інформація Щоб надіслати дані, ви повинні використовувати один із: `POST` (більш поширений), `PUT`, `DELETE` або `PATCH`. @@ -18,21 +18,22 @@ /// -## Імпортуйте `BaseModel` від Pydantic +## Імпортуйте `BaseModel` від Pydantic { #import-pydantics-basemodel } Спочатку вам потрібно імпортувати `BaseModel` з `pydantic`: -{* ../../docs_src/body/tutorial001.py hl[4] *} +{* ../../docs_src/body/tutorial001_py310.py hl[2] *} -## Створіть свою модель даних +## Створіть свою модель даних { #create-your-data-model } Потім ви оголошуєте свою модель даних як клас, який успадковується від `BaseModel`. Використовуйте стандартні типи Python для всіх атрибутів: -{* ../../docs_src/body/tutorial001.py hl[7:11] *} +{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *} -Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте `None`, щоб зробити його необов'язковим. + +Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте `None`, щоб зробити його просто необов'язковим. Наприклад, ця модель вище оголошує JSON "`об'єкт`" (або Python `dict`), як: @@ -54,15 +55,15 @@ } ``` -## Оголоси її як параметр +## Оголосіть її як параметр { #declare-it-as-a-parameter } Щоб додати модель даних до вашої *операції шляху*, оголосіть її так само, як ви оголосили параметри шляху та запиту: -{* ../../docs_src/body/tutorial001.py hl[18] *} +{* ../../docs_src/body/tutorial001_py310.py hl[16] *} ...і вкажіть її тип як модель, яку ви створили, `Item`. -## Результати +## Результати { #results } Лише з цим оголошенням типу Python **FastAPI** буде: @@ -73,9 +74,9 @@ * Надавати отримані дані у параметрі `item`. * Оскільки ви оголосили його у функції як тип `Item`, ви також матимете всю підтримку редактора (автозаповнення, тощо) для всіх атрибутів та їх типів. * Генерувати JSON Schema визначення для вашої моделі, ви також можете використовувати їх де завгодно, якщо це має сенс для вашого проекту. -* Ці схеми будуть частиною згенерованої схеми OpenAPI і використовуватимуться автоматичною документацією інтерфейсу користувача. +* Ці схеми будуть частиною згенерованої схеми OpenAPI і використовуватимуться автоматичною документацією UIs. -## Автоматична документація +## Автоматична документація { #automatic-docs } Схеми JSON ваших моделей будуть частиною вашої схеми, згенерованої OpenAPI, і будуть показані в інтерактивній API документації: @@ -85,7 +86,7 @@ -## Підтримка редактора +## Підтримка редактора { #editor-support } У вашому редакторі, всередині вашої функції, ви будете отримувати підказки типу та завершення скрізь (це б не сталося, якби ви отримали `dict` замість моделі Pydantic): @@ -107,7 +108,7 @@ -/// tip +/// tip | Порада Якщо ви використовуєте PyCharm як ваш редактор, ви можете використати Pydantic PyCharm Plugin. @@ -121,42 +122,45 @@ /// -## Використовуйте модель +## Використовуйте модель { #use-the-model } Усередині функції ви можете отримати прямий доступ до всіх атрибутів об’єкта моделі: -{* ../../docs_src/body/tutorial002.py hl[21] *} +{* ../../docs_src/body/tutorial002_py310.py *} -## Тіло запиту + параметри шляху +## Тіло запиту + параметри шляху { #request-body-path-parameters } Ви можете одночасно оголошувати параметри шляху та тіло запиту. **FastAPI** розпізнає, що параметри функції, які відповідають параметрам шляху, мають бути **взяті з шляху**, а параметри функції, які оголошуються як моделі Pydantic, **взяті з тіла запиту**. -{* ../../docs_src/body/tutorial003.py hl[17:18] *} +{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *} + -## Тіло запиту + шлях + параметри запиту +## Тіло запиту + шлях + параметри запиту { #request-body-path-query-parameters } Ви також можете оголосити параметри **тіло**, **шлях** і **запит** одночасно. **FastAPI** розпізнає кожен з них і візьме дані з потрібного місця. -{* ../../docs_src/body/tutorial004.py hl[18] *} +{* ../../docs_src/body/tutorial004_py310.py hl[16] *} Параметри функції будуть розпізнаватися наступним чином: * Якщо параметр також оголошено в **шляху**, він використовуватиметься як параметр шляху. * Якщо параметр має **сингулярний тип** (наприклад, `int`, `float`, `str`, `bool` тощо), він буде інтерпретуватися як параметр **запиту**. -* Якщо параметр оголошується як тип **Pydantic моделі**, він інтерпретується як **тіло** запиту. +* Якщо параметр оголошується як тип **Pydantic моделі**, він інтерпретується як **тіло** **запиту**. + +/// note | Примітка -/// note +FastAPI буде знати, що значення `q` не є обов'язковим через значення за замовчуванням `= None`. -FastAPI буде знати, що значення "q" не є обов'язковим через значення за замовчуванням "= None". +`str | None` (Python 3.10+) або `Union` у `Union[str, None]` (Python 3.9+) FastAPI не використовує, щоб визначити, що значення не є обов’язковим — він знатиме, що воно не є обов’язковим, тому що має значення за замовчуванням `= None`. -`Optional` у `Optional[str]` не використовується FastAPI, але дозволить вашому редактору надати вам кращу підтримку та виявляти помилки. +Але додавання анотацій типів дозволить вашому редактору надати вам кращу підтримку та виявляти помилки. /// -## Без Pydantic +## Без Pydantic { #without-pydantic } -Якщо ви не хочете використовувати моделі Pydantic, ви також можете використовувати параметри **Body**. Перегляньте документацію для [Тіло – Кілька параметрів: сингулярні значення в тілі](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. +Якщо ви не хочете використовувати моделі Pydantic, ви також можете використовувати параметри **Body**. Перегляньте документацію для [Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. diff --git a/docs/uk/docs/tutorial/cookie-param-models.md b/docs/uk/docs/tutorial/cookie-param-models.md index f070b6ac83..3c6407716e 100644 --- a/docs/uk/docs/tutorial/cookie-param-models.md +++ b/docs/uk/docs/tutorial/cookie-param-models.md @@ -1,32 +1,32 @@ -# Моделі для Cookie-параметрів +# Моделі параметрів Cookie { #cookie-parameter-models } -Якщо у Вас є група **cookies** параметрів, які пов'язані між собою, Ви можете створити **Pydantic-модель**, щоб оголосити їх. 🍪 +Якщо у Вас є група **cookies**, які пов'язані між собою, Ви можете створити **Pydantic-модель**, щоб оголосити їх. 🍪 Це дозволить Вам повторно **використовувати модель** у **різних місцях**, а також оголосити валідацію та метадані для всіх параметрів одночасно. 😎 -/// note | Нотатки +/// note | Примітка -Це підтримується з версії FastAPI `0.115.0`. 🤓 +Це підтримується з версії FastAPI `0.115.0`. 🤓 /// /// tip | Порада -Ця ж техніка застосовується до `Query`, `Cookie`, та `Header`. 😎 +Ця ж техніка застосовується до `Query`, `Cookie` та `Header`. 😎 /// -## Cookie з Pydantic-моделлю +## Cookie з Pydantic-моделлю { #cookies-with-a-pydantic-model } -Оголосіть **cookie-параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть параметр як `Cookie`: +Оголосіть **cookie**-параметри, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть параметр як `Cookie`: {* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *} -**FastAPI** буде **витягувати** дані для **кожного поля** з **cookie** параметрів, отриманих у запиті, і передавати Вам Pydantic-модель, яку Ви визначили. +**FastAPI** буде **витягувати** дані для **кожного поля** з **cookies**, отриманих у запиті, і передавати Вам Pydantic-модель, яку Ви визначили. -## Перевірка у документації +## Перевірка у документації { #check-the-docs } -Ви можете побачити визначені cookie в інтерфейсі документації за адресою `/docs`: +Ви можете побачити визначені cookies в інтерфейсі документації за адресою `/docs`:
@@ -34,29 +34,29 @@ /// info | Інформація -Майте на увазі, що оскільки **браузери обробляють cookie** особливим чином і "за лаштунками", вони **не** дозволяють **JavaScript** легко з ними працювати. +Майте на увазі, що оскільки **браузери обробляють cookies** особливим чином і «за лаштунками», вони **не** дозволяють **JavaScript** легко з ними працювати. -Якщо Ви зайдете до **інтерфейсу документації API** за адресою `/docs`, Ви зможете побачити **документацію** для cookie у Ваших **операціях шляху**. +Якщо Ви зайдете до **інтерфейсу документації API** за адресою `/docs`, Ви зможете побачити **документацію** для cookies у Ваших *операціях шляху*. -Але навіть якщо Ви заповните дані й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookie не будуть відправлені, і Ви побачите **помилку**, ніби Ви не ввели жодних значень. +Але навіть якщо Ви заповните дані й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не будуть відправлені, і Ви побачите **помилку**, ніби Ви не ввели жодних значень. /// -## Заборона додаткових cookie +## Заборона додаткових cookie { #forbid-extra-cookies } -У деяких спеціальних випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** список cookie, які хочете отримувати. +У деяких спеціальних випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** cookies, які хочете отримувати. -Ваша API тепер має можливість контролювати власну згоду на cookie. 🤪🍪 +Ваша API тепер має можливість контролювати власну згоду на cookie. 🤪🍪 -Ви можете використовувати налаштування моделі Pydantic, щоб `заборонити` будь-які `додаткові` поля: +Ви можете використовувати налаштування моделі Pydantic, щоб `forbid` будь-які `extra` поля: -{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *} +{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *} -Якщо клієнт спробує надіслати якісь **додаткові cookie**, він отримає відповідь з **помилкою**. +Якщо клієнт спробує надіслати якісь **додаткові cookies**, він отримає відповідь з **помилкою**. -Бідні банери cookie, які так старанно намагаються отримати Вашу згоду, щоб API її відхилила. 🍪 +Бідні банери cookie, які так старанно намагаються отримати Вашу згоду, щоб API її відхилила. 🍪 -Наприклад, якщо клієнт спробує надіслати cookie `santa_tracker` зі значенням `good-list-please`, він отримає відповідь з помилкою, яка повідомить, що cookie `santa_tracker` не дозволено: +Наприклад, якщо клієнт спробує надіслати cookie `santa_tracker` зі значенням `good-list-please`, він отримає відповідь з помилкою, яка повідомить, що `santa_tracker` cookie не дозволено: ```json { @@ -71,6 +71,6 @@ } ``` -## Підсумок +## Підсумок { #summary } -Ви можете використовувати **Pydantic-моделі** для оголошення cookie у FastAPI. 😎 +Ви можете використовувати **Pydantic-моделі** для оголошення **cookies** у **FastAPI**. 😎 diff --git a/docs/uk/docs/tutorial/cookie-params.md b/docs/uk/docs/tutorial/cookie-params.md index b320645cb3..8a5b44e8aa 100644 --- a/docs/uk/docs/tutorial/cookie-params.md +++ b/docs/uk/docs/tutorial/cookie-params.md @@ -1,24 +1,25 @@ -# Параметри Cookie +# Параметри Cookie { #cookie-parameters } -Ви можете визначити параметри Cookie таким же чином, як визначаються параметри `Query` і `Path`. +Ви можете визначати параметри Cookie таким же чином, як визначаються параметри `Query` і `Path`. -## Імпорт `Cookie` +## Імпорт `Cookie` { #import-cookie } Спочатку імпортуйте `Cookie`: {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *} -## Визначення параметрів `Cookie` +## Визначення параметрів `Cookie` { #declare-cookie-parameters } Потім визначте параметри cookie, використовуючи таку ж конструкцію як для `Path` і `Query`. -Перше значення це значення за замовчуванням, ви можете також передати всі додаткові параметри валідації чи анотації: +Ви можете визначити значення за замовчуванням, а також усі додаткові параметри валідації чи анотації: {* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *} -/// note | Технічні Деталі +/// note | Технічні деталі + +`Cookie` це "сестра" класів `Path` і `Query`. Вони також наслідуються від одного спільного класу `Param`. -`Cookie` це "сестра" класів `Path` і `Query`. Вони наслідуються від одного батьківського класу `Param`. Але пам'ятайте, що коли ви імпортуєте `Query`, `Path`, `Cookie` та інше з `fastapi`, це фактично функції, що повертають спеціальні класи. /// @@ -29,6 +30,16 @@ /// -## Підсумки +/// info + +Майте на увазі, що оскільки **браузери обробляють cookies** спеціальним чином і за лаштунками, вони **не** дозволяють **JavaScript** легко взаємодіяти з ними. + +Якщо ви перейдете до **інтерфейсу документації API** за адресою `/docs`, ви зможете побачити **документацію** для cookies для ваших *операцій шляху*. + +Але навіть якщо ви **заповните дані** і натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не буде надіслано, і ви побачите повідомлення про **помилку**, ніби ви не ввели жодних значень. + +/// + +## Підсумки { #recap } Визначайте cookies за допомогою `Cookie`, використовуючи той же спільний шаблон, що і `Query` та `Path`. diff --git a/docs/uk/docs/tutorial/cors.md b/docs/uk/docs/tutorial/cors.md index 95b204d0f7..f3ed8a7d94 100644 --- a/docs/uk/docs/tutorial/cors.md +++ b/docs/uk/docs/tutorial/cors.md @@ -1,8 +1,8 @@ -# CORS (Обмін ресурсами між різними джерелами) +# CORS (Обмін ресурсами між різними джерелами) { #cors-cross-origin-resource-sharing } -CORS або "Обмін ресурсами між різними джерелами" є ситуація, коли фронтенд, що працює в браузері, містить JavaScript-код, який взаємодіє з бекендом, розташованим в іншому "джерелі" (origin). +CORS або "Cross-Origin Resource Sharing" є ситуація, коли фронтенд, що працює в браузері, містить JavaScript-код, який взаємодіє з бекендом, розташованим в іншому "джерелі" (origin). -## Джерело (Origin) +## Джерело (Origin) { #origin } Джерело визначається комбінацією протоколу (`http`, `https`), домену (`myapp.com`, `localhost`, `localhost.tiangolo.com`), порту (`80`, `443`, `8080`). @@ -15,7 +15,7 @@ Навіть якщо вони всі містять `localhost`, вони мають різні протоколи або порти, що робить їх окремими "джерелами". -## Кроки +## Кроки { #steps } Припустимо, що Ваш фронтенд працює в браузері на `http://localhost:8080`, а його JavaScript намагається відправити запит до бекенду, який працює на `http://localhost` (Оскільки ми не вказуємо порт, браузер за замовчуванням припускає порт `80`). @@ -25,15 +25,15 @@ У цьому випадку список має містити `http://localhost:8080`, щоб фронтенд на порту `:8080` працював коректно. -## Символьне підставляння +## Символьне підставляння { #wildcards } Можна також оголосити список як `"*"` ("символьне підставляння"), що означає дозвіл для всіх джерел. -Однак це дозволить лише певні типи комунікації, виключаючи все, що пов'язане з обліковими даними: Cookies, заголовки авторизації, такі як ті, що використовуються з Bearer токенами тощо. +Однак це дозволить лише певні типи комунікації, виключаючи все, що пов'язане з обліковими даними: Cookies, заголовки авторизації, такі як ті, що використовуються з Bearer Tokens, тощо. Тому для коректної роботи краще явно вказувати дозволені джерела. -## Використання `CORSMiddleware` +## Використання `CORSMiddleware` { #use-corsmiddleware } Ви можете налаштувати це у Вашому додатку **FastAPI** за допомогою `CORSMiddleware`. @@ -44,41 +44,44 @@ Також можна вказати, чи дозволяє Ваш бекенд: -* Облікові дані (заголовки авторизації, сookies, тощо). +* Облікові дані (заголовки авторизації, Cookies, тощо). * Конкретні HTTP-методи (`POST`, `PUT`) або всі за допомогою `"*"` * Конкретні HTTP-заголовки або всі за допомогою `"*"`. -{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *} +{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *} -Параметри за замовчуванням у `CORSMiddleware` є досить обмеженими, тому Вам потрібно явно вказати конкретні джерела, методи або заголовки, щоб браузери могли використовувати їх у контексті запитів між різними доменами. +Параметри за замовчуванням у реалізації `CORSMiddleware` є досить обмеженими, тому Вам потрібно явно увімкнути конкретні джерела, методи або заголовки, щоб браузерам було дозволено використовувати їх у міждоменному контексті. Підтримуються такі аргументи: -* `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_methods` - Список HTTP-методів, дозволених для міждоменних запитів. За замовчуванням `['GET']`. Ви можете використовувати `['*']`, щоб дозволити всі стандартні методи. -* `allow_headers` - Список HTTP-заголовків, які підтримуються для міждоменних запитів. За замовчуванням `[]`. Ви можете використовувати `['*']`, щоб дозволити всі заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` і `Content-Type` завжди дозволені для простих CORS-запитів. -* `allow_credentials` - Визначає, чи підтримуються файли cookie для міждоменних запитів. За замовчуванням `False`. Також, якщо потрібно дозволити обмін обліковими даними (`allow_credentials = True`), параметр `allow_origins` не може бути встановлений як `['*']`, необхідно вказати конкретні джерела. +* `allow_headers` - Список HTTP-заголовків запиту, які підтримуються для міждоменних запитів. За замовчуванням `[]`. Ви можете використовувати `['*']`, щоб дозволити всі заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` і `Content-Type` завжди дозволені для простих CORS-запитів. +* `allow_credentials` - Визначає, чи повинні підтримуватися cookies для міждоменних запитів. За замовчуванням `False`. + + Жоден із параметрів `allow_origins`, `allow_methods` і `allow_headers` не можна встановлювати як `['*']`, якщо `allow_credentials` встановлено як `True`. Усі вони мають бути явно вказані. + * `expose_headers` - Вказує, які заголовки відповіді повинні бути доступні для браузера. За замовчуванням `[]`. * `max_age` - Встановлює максимальний час (у секундах) для кешування CORS-відповідей у браузерах. За замовчуванням `600`. Цей middleware обробляє два типи HTTP-запитів... -### Попередні CORS-запити (preflight requests) +### Попередні CORS-запити { #cors-preflight-requests } Це будь-які `OPTIONS` - запити, що містять заголовки `Origin` та `Access-Control-Request-Method`. У такому випадку middleware перехопить вхідний запит і відповість відповідними CORS-заголовками, повертаючи або `200`, або `400` для інформаційних цілей. -### Прості запити +### Прості запити { #simple-requests } Будь-які запити із заголовком `Origin`. У цьому випадку middleware пропустить запит як звичайний, але додасть відповідні CORS-заголовки у відповідь. -## Додаткова інформація +## Додаткова інформація { #more-info } -Більше про CORS можна дізнатися в документації Mozilla. +Більше про CORS можна дізнатися в документації Mozilla про CORS. /// note | Технічні деталі diff --git a/docs/uk/docs/tutorial/debugging.md b/docs/uk/docs/tutorial/debugging.md index b0e5344f81..0db418dcc9 100644 --- a/docs/uk/docs/tutorial/debugging.md +++ b/docs/uk/docs/tutorial/debugging.md @@ -1,16 +1,16 @@ -# Налагодження (Debugging) +# Налагодження { #debugging } -Ви можете під'єднати дебагер у Вашому редакторі коду, наприклад, у Visual Studio Code або PyCharm. +Ви можете під'єднати дебагер у вашому редакторі коду, наприклад, у Visual Studio Code або PyCharm. -## Виклик `uvicorn` +## Виклик `uvicorn` { #call-uvicorn } -У Вашому FastAPI-додатку імпортуйте та запустіть `uvicorn` безпосередньо: +У вашому FastAPI-додатку імпортуйте та запустіть `uvicorn` безпосередньо: -{* ../../docs_src/debugging/tutorial001.py hl[1,15] *} +{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *} -### Про `__name__ == "__main__"` +### Про `__name__ == "__main__"` { #about-name-main } -Головна мета використання `__name__ == "__main__"` — це забезпечення виконання певного коду тільки тоді, коли файл запускається безпосередньо: +Головна мета використання `__name__ == "__main__"` — це забезпечення виконання певного коду лише тоді, коли ваш файл запускається так:
@@ -20,17 +20,17 @@ $ python myapp.py
-але не виконується при його імпорті в інший файл, наприклад: +але не виконується, коли інший файл імпортує його, наприклад: ```Python from myapp import app ``` -#### Детальніше +#### Детальніше { #more-details } -Припустимо, Ваш файл називається `myapp.py`. +Припустимо, ваш файл називається `myapp.py`. -Якщо Ви запустите його так: +Якщо ви запустите його так:
@@ -40,7 +40,7 @@ $ python myapp.py
-тоді внутрішня змінна `__name__`, яка створюється автоматично Python, матиме значення `"__main__"`. +тоді внутрішня змінна `__name__` у вашому файлі, яка створюється автоматично Python, матиме значення рядка `"__main__"`. Отже, цей блок коду: @@ -52,17 +52,17 @@ $ python myapp.py --- -Це не станеться, якщо Ви імпортуєте цей модуль (файл). +Це не станеться, якщо ви імпортуєте цей модуль (файл). -Якщо у Вас є інший файл, наприклад `importer.py`, з наступним кодом: +Отже, якщо у вас є інший файл `importer.py` з: ```Python from myapp import app -# Додатковий код +# Some more code ``` -У цьому випадку автоматично створена змінна у файлі `myapp.py` не матиме значення змінної `__name__` як `"__main__"`. +у цьому випадку автоматично створена змінна `__name__` всередині `myapp.py` не матиме значення `"__main__"`. Отже, рядок: @@ -74,38 +74,39 @@ from myapp import app /// info | Інформація -Більш детальну інформацію можна знайти в офіційній документації Python. +Для отримання додаткової інформації дивіться офіційну документацію Python. /// -## Запуск коду з вашим дебагером +## Запуск коду з вашим дебагером { #run-your-code-with-your-debugger } -Оскільки Ви запускаєте сервер Uvicorn безпосередньо з Вашого коду, Ви можете запустити вашу Python програму (ваш FastAPI додаток) безпосередньо з дебагера. +Оскільки ви запускаєте сервер Uvicorn безпосередньо з вашого коду, ви можете запустити вашу Python програму (ваш FastAPI-додаток) безпосередньо з дебагера. --- -Наприклад, у Visual Studio Code Ви можете: +Наприклад, у Visual Studio Code ви можете: -* Перейдіть на вкладку "Debug". -* Натисніть "Add configuration...". -* Виберіть "Python" +* Перейдіть на панель «Debug». +* «Add configuration...». +* Виберіть «Python» * Запустіть дебагер з опцією "`Python: Current File (Integrated Terminal)`". -Це запустить сервер з Вашим **FastAPI** кодом, зупиниться на точках зупину тощо. +Після цього він запустить сервер з вашим кодом **FastAPI**, зупиниться на точках зупину тощо. Ось як це може виглядати: --- -Якщо Ви використовуєте PyCharm, ви можете: -* Відкрити меню "Run". -* Вибрати опцію "Debug...". +Якщо ви використовуєте PyCharm, ви можете: + +* Відкрити меню «Run». +* Вибрати опцію «Debug...». * Потім з'явиться контекстне меню. * Вибрати файл для налагодження (у цьому випадку, `main.py`). -Це запустить сервер з Вашим **FastAPI** кодом, зупиниться на точках зупину тощо. +Після цього він запустить сервер з вашим кодом **FastAPI**, зупиниться на точках зупину тощо. Ось як це може виглядати: diff --git a/docs/uk/docs/tutorial/encoder.md b/docs/uk/docs/tutorial/encoder.md index f202c7989e..1b403d5bba 100644 --- a/docs/uk/docs/tutorial/encoder.md +++ b/docs/uk/docs/tutorial/encoder.md @@ -1,32 +1,32 @@ -# JSON Compatible Encoder +# JSON-сумісний кодувальник { #json-compatible-encoder } -Існують випадки, коли вам може знадобитися перетворити тип даних (наприклад, модель Pydantic) в щось сумісне з JSON (наприклад, `dict`, `list`, і т. д.). +Існують випадки, коли вам може знадобитися перетворити тип даних (наприклад, модель Pydantic) на щось сумісне з JSON (наприклад, `dict`, `list` тощо). Наприклад, якщо вам потрібно зберегти це в базі даних. -Для цього, **FastAPI** надає `jsonable_encoder()` функцію. +Для цього **FastAPI** надає функцію `jsonable_encoder()`. -## Використання `jsonable_encoder` +## Використання `jsonable_encoder` { #using-the-jsonable-encoder } Давайте уявимо, що у вас є база даних `fake_db`, яка приймає лише дані, сумісні з JSON. Наприклад, вона не приймає об'єкти типу `datetime`, оскільки вони не сумісні з JSON. -Отже, об'єкт типу `datetime` потрібно перетворити в рядок `str`, який містить дані в ISO форматі. +Отже, об'єкт типу `datetime` потрібно перетворити на `str`, який містить дані в форматі ISO. -Тим самим способом ця база даних не прийматиме об'єкт типу Pydantic model (об'єкт з атрибутами), а лише `dict`. +Так само ця база даних не прийматиме модель Pydantic (об'єкт з атрибутами), а лише `dict`. Ви можете використовувати `jsonable_encoder` для цього. -Вона приймає об'єкт, такий як Pydantic model, і повертає його версію, сумісну з JSON: +Вона приймає об'єкт, такий як модель Pydantic, і повертає його версію, сумісну з JSON: {* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *} -У цьому прикладі вона конвертує Pydantic model у `dict`, а `datetime` у `str`. +У цьому прикладі вона конвертує модель Pydantic у `dict`, а `datetime` у `str`. -Результат виклику цієї функції - це щось, що можна кодувати з використанням стандарту Python `json.dumps()`. +Результат виклику цієї функції — це щось, що можна кодувати з використанням стандарту Python `json.dumps()`. -Вона не повертає велику строку `str`, яка містить дані у форматі JSON (як строка). Вона повертає стандартну структуру даних Python (наприклад `dict`) із значеннями та підзначеннями, які є сумісними з JSON. +Вона не повертає великий `str`, який містить дані у форматі JSON (як рядок). Вона повертає стандартну структуру даних Python (наприклад, `dict`) зі значеннями та підзначеннями, які є сумісними з JSON. /// note | Примітка diff --git a/docs/uk/docs/tutorial/extra-data-types.md b/docs/uk/docs/tutorial/extra-data-types.md index 5da942b6e0..a3545e0746 100644 --- a/docs/uk/docs/tutorial/extra-data-types.md +++ b/docs/uk/docs/tutorial/extra-data-types.md @@ -1,13 +1,13 @@ -# Додаткові типи даних +# Додаткові типи даних { #extra-data-types } -До цього часу, ви використовували загальнопоширені типи даних, такі як: +До цього часу ви використовували загальнопоширені типи даних, такі як: * `int` * `float` * `str` * `bool` -Але можна також використовувати більш складні типи даних. +Але ви також можете використовувати більш складні типи даних. І ви все ще матимете ті ж можливості, які були показані до цього: @@ -17,30 +17,30 @@ * Валідація даних. * Автоматична анотація та документація. -## Інші типи даних +## Інші типи даних { #other-data-types } Ось додаткові типи даних для використання: * `UUID`: - * Стандартний "Універсальний Унікальний Ідентифікатор", який часто використовується як ідентифікатор у багатьох базах даних та системах. + * Стандартний "Універсальний унікальний ідентифікатор", який часто використовується як ID у багатьох базах даних та системах. * У запитах та відповідях буде представлений як `str`. * `datetime.datetime`: * Пайтонівський `datetime.datetime`. - * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `2008-09-15T15:53:00+05:00`. + * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `2008-09-15T15:53:00+05:00`. * `datetime.date`: * Пайтонівський `datetime.date`. - * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `2008-09-15`. + * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `2008-09-15`. * `datetime.time`: * Пайтонівський `datetime.time`. - * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `14:23:55.003`. + * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `14:23:55.003`. * `datetime.timedelta`: * Пайтонівський `datetime.timedelta`. * У запитах та відповідях буде представлений як `float` загальної кількості секунд. - * Pydantic також дозволяє представляти це як "ISO 8601 time diff encoding", більше інформації дивись у документації. + * Pydantic також дозволяє представляти це як "ISO 8601 time diff encoding", дивіться документацію для отримання додаткової інформації. * `frozenset`: * У запитах і відповідях це буде оброблено так само, як і `set`: - * У запитах список буде зчитано, дублікати будуть видалені та він буде перетворений на `set`. - * У відповідях, `set` буде перетворений на `list`. + * У запитах список буде зчитано, дублікати буде видалено, і його буде перетворено на `set`. + * У відповідях `set` буде перетворено на `list`. * Згенерована схема буде вказувати, що значення `set` є унікальними (з використанням JSON Schema's `uniqueItems`). * `bytes`: * Стандартний Пайтонівський `bytes`. @@ -49,11 +49,11 @@ * `Decimal`: * Стандартний Пайтонівський `Decimal`. * У запитах і відповідях це буде оброблено так само, як і `float`. -* Ви можете перевірити всі дійсні типи даних Pydantic тут: типи даних Pydantic. +* Ви можете перевірити всі дійсні типи даних Pydantic тут: типи даних Pydantic. -## Приклад +## Приклад { #example } -Ось приклад *path operation* з параметрами, використовуючи деякі з вищезазначених типів. +Ось приклад *операції шляху* з параметрами, використовуючи деякі з вищезазначених типів. {* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *} diff --git a/docs/uk/docs/tutorial/first-steps.md b/docs/uk/docs/tutorial/first-steps.md index 3f861cb484..5f3750010c 100644 --- a/docs/uk/docs/tutorial/first-steps.md +++ b/docs/uk/docs/tutorial/first-steps.md @@ -1,126 +1,118 @@ -# Перші кроки +# Перші кроки { #first-steps } Найпростіший файл FastAPI може виглядати так: -{* ../../docs_src/first_steps/tutorial001.py *} +{* ../../docs_src/first_steps/tutorial001_py39.py *} Скопіюйте це до файлу `main.py`. -Запустіть сервер: +Запустіть live-сервер:
```console -$ fastapi dev main.py -INFO Using path main.py -INFO Resolved absolute path /home/user/code/awesomeapp/main.py -INFO Searching for package file structure from directories with __init__.py files -INFO Importing from /home/user/code/awesomeapp - - ╭─ Python module file ─╮ - │ │ - │ 🐍 main.py │ - │ │ - ╰──────────────────────╯ - -INFO Importing module main -INFO Found importable FastAPI app - - ╭─ Importable FastAPI app ─╮ - │ │ - │ from main import app │ - │ │ - ╰──────────────────────────╯ - -INFO Using import string main:app - - ╭────────── FastAPI CLI - Development mode ───────────╮ - │ │ - │ Serving at: http://127.0.0.1:8000 │ - │ │ - │ API docs: http://127.0.0.1:8000/docs │ - │ │ - │ Running in development mode, for production use: │ - │ │ - │ fastapi run │ - │ │ - ╰─────────────────────────────────────────────────────╯ - -INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [2265862] using WatchFiles -INFO: Started server process [2265873] -INFO: Waiting for application startup. -INFO: Application startup complete. +$ fastapi dev main.py + + FastAPI Starting development server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run + + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C + to quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
-У консолі буде рядок приблизно такого змісту: +У виводі є рядок приблизно такого змісту: ```hl_lines="4" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` -Цей рядок показує URL, за яким додаток запускається на вашій локальній машині. +Цей рядок показує URL, за яким ваш застосунок обслуговується на вашій локальній машині. -### Перевірте +### Перевірте { #check-it } Відкрийте браузер та введіть адресу http://127.0.0.1:8000. -Ви побачите у відповідь таке повідомлення у форматі JSON: +Ви побачите JSON-відповідь: ```JSON {"message": "Hello World"} ``` -### Інтерактивна API документація +### Інтерактивна API документація { #interactive-api-docs } -Перейдемо сюди http://127.0.0.1:8000/docs. +Тепер перейдіть сюди http://127.0.0.1:8000/docs. -Ви побачите автоматичну інтерактивну API документацію (створену завдяки Swagger UI): +Ви побачите автоматичну інтерактивну API документацію (надається Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) -### Альтернативна API документація +### Альтернативна API документація { #alternative-api-docs } -Тепер перейдемо сюди http://127.0.0.1:8000/redoc. +А тепер перейдіть сюди http://127.0.0.1:8000/redoc. -Ви побачите альтернативну автоматичну документацію (створену завдяки ReDoc): +Ви побачите альтернативну автоматичну документацію (надається ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) -### OpenAPI +### OpenAPI { #openapi } -**FastAPI** генерує "схему" з усім вашим API, використовуючи стандарт **OpenAPI** для визначення API. +**FastAPI** генерує «схему» з усім вашим API, використовуючи стандарт **OpenAPI** для визначення API. -#### "Схема" +#### «Схема» { #schema } -"Схема" - це визначення або опис чогось. Це не код, який його реалізує, а просто абстрактний опис. +«Схема» — це визначення або опис чогось. Це не код, який його реалізує, а просто абстрактний опис. -#### API "схема" +#### API «схема» { #api-schema } У цьому випадку, OpenAPI є специфікацією, яка визначає, як описати схему вашого API. -Це визначення схеми включає шляхи (paths) вашого API, можливі параметри, які вони приймають тощо. +Це визначення схеми включає шляхи (paths) вашого API, можливі параметри, які вони приймають, тощо. -#### "Схема" даних +#### «Схема» даних { #data-schema } -Термін "схема" також може відноситися до структури даних, наприклад, JSON. +Термін «схема» також може відноситися до форми деяких даних, наприклад, вмісту JSON. -У цьому випадку це означає - атрибути JSON і типи даних, які вони мають тощо. +У цьому випадку це означає атрибути JSON і типи даних, які вони мають, тощо. -#### OpenAPI і JSON Schema +#### OpenAPI і JSON Schema { #openapi-and-json-schema } -OpenAPI описує схему для вашого API. І ця схема включає визначення (або "схеми") даних, що надсилаються та отримуються вашим API за допомогою **JSON Schema**, стандарту для схем даних JSON. +OpenAPI описує схему API для вашого API. І ця схема включає визначення (або «схеми») даних, що надсилаються та отримуються вашим API, за допомогою **JSON Schema**, стандарту для схем даних JSON. -#### Розглянемо `openapi.json` +#### Перевірте `openapi.json` { #check-the-openapi-json } -Якщо вас цікавить, як виглядає вихідна схема OpenAPI, то FastAPI автоматично генерує JSON-схему з усіма описами API. +Якщо вас цікавить, як виглядає «сирий» OpenAPI schema, FastAPI автоматично генерує JSON (schema) з описами всього вашого API. -Ознайомитися можна за посиланням: http://127.0.0.1:8000/openapi.json. +Ви можете побачити це напряму тут: http://127.0.0.1:8000/openapi.json. -Ви побачите приблизно такий JSON: +Ви побачите JSON, що починається приблизно так: ```JSON { @@ -143,42 +135,79 @@ OpenAPI описує схему для вашого API. І ця схема вк ... ``` -#### Для чого потрібний OpenAPI +#### Для чого потрібний OpenAPI { #what-is-openapi-for } + +OpenAPI schema — це те, на чому працюють дві включені системи інтерактивної документації. + +Також існують десятки альтернатив, і всі вони засновані на OpenAPI. Ви можете легко додати будь-яку з цих альтернатив до вашого застосунку, створеного з **FastAPI**. -Схема OpenAPI є основою для обох систем інтерактивної документації. +Ви також можете використовувати його для автоматичної генерації коду для клієнтів, які взаємодіють з вашим API. Наприклад, для фронтенд-, мобільних або IoT-застосунків. -Існують десятки альтернативних інструментів, заснованих на OpenAPI. Ви можете легко додати будь-який з них до **FastAPI** додатку. +### Розгорніть ваш застосунок (необовʼязково) { #deploy-your-app-optional } -Ви також можете використовувати OpenAPI для автоматичної генерації коду для клієнтів, які взаємодіють з API. Наприклад, для фронтенд-, мобільних або IoT-додатків +За бажанням ви можете розгорнути ваш FastAPI-застосунок у FastAPI Cloud, перейдіть і приєднайтеся до списку очікування, якщо ви цього ще не зробили. 🚀 -## А тепер крок за кроком +Якщо у вас вже є обліковий запис **FastAPI Cloud** (ми запросили вас зі списку очікування 😉), ви можете розгорнути ваш застосунок однією командою. -### Крок 1: імпортуємо `FastAPI` +Перед розгортанням переконайтеся, що ви увійшли: -{* ../../docs_src/first_steps/tutorial001.py hl[1] *} +
+ +```console +$ fastapi login + +You are logged in to FastAPI Cloud 🚀 +``` + +
+ +Потім розгорніть ваш застосунок: + +
+ +```console +$ fastapi deploy -`FastAPI` це клас у Python, який надає всю функціональність для API. +Deploying to FastAPI Cloud... + +✅ Deployment successful! + +🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev +``` + +
+ +Ось і все! Тепер ви можете отримати доступ до вашого застосунку за цим URL. ✨ + +## Підібʼємо підсумки, крок за кроком { #recap-step-by-step } + +### Крок 1: імпортуємо `FastAPI` { #step-1-import-fastapi } + +{* ../../docs_src/first_steps/tutorial001_py39.py hl[1] *} + +`FastAPI` — це клас у Python, який надає всю функціональність для вашого API. /// note | Технічні деталі -`FastAPI` це клас, який успадковується безпосередньо від `Starlette`. +`FastAPI` — це клас, який успадковується безпосередньо від `Starlette`. Ви також можете використовувати всю функціональність Starlette у `FastAPI`. /// -### Крок 2: створюємо екземпляр `FastAPI` +### Крок 2: створюємо «екземпляр» `FastAPI` { #step-2-create-a-fastapi-instance } + +{* ../../docs_src/first_steps/tutorial001_py39.py hl[3] *} -{* ../../docs_src/first_steps/tutorial001.py hl[3] *} -Змінна `app` є екземпляром класу `FastAPI`. +Тут змінна `app` буде «екземпляром» класу `FastAPI`. -Це буде головна точка для створення і взаємодії з API. +Це буде головна точка взаємодії для створення всього вашого API. -### Крок 3: визначте операцію шляху (path operation) +### Крок 3: створіть *операцію шляху* { #step-3-create-a-path-operation } -#### Шлях (path) +#### Шлях { #path } -"Шлях" це частина URL, яка йде одразу після символу `/`. +«Шлях» тут означає останню частину URL, починаючи з першого `/`. Отже, у такому URL, як: @@ -192,16 +221,17 @@ https://example.com/items/foo /items/foo ``` -/// info | Додаткова інформація +/// info | Інформація -"Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route). +«Шлях» також зазвичай називають «ендпоінтом» або «маршрутом». /// -При створенні API, "шлях" є основним способом розділення "завдань" і "ресурсів". -#### Operation +Під час створення API «шлях» є основним способом розділити «завдання» і «ресурси». + +#### Операція { #operation } -"Операція" (operation) тут означає один з "методів" HTTP. +«Операція» тут означає один з HTTP «методів». Один з: @@ -217,46 +247,47 @@ https://example.com/items/foo * `PATCH` * `TRACE` -У HTTP-протоколі можна спілкуватися з кожним шляхом, використовуючи один (або кілька) з цих "методів". +У протоколі HTTP ви можете спілкуватися з кожним шляхом, використовуючи один (або кілька) з цих «методів». --- -При створенні API зазвичай використовуються конкретні методи HTTP для виконання певних дій. +Під час створення API зазвичай використовують ці конкретні HTTP методи, щоб виконати певну дію. -Як правило, використовують: +Зазвичай використовують: -* `POST`: для створення даних. -* `GET`: для читання даних. -* `PUT`: для оновлення даних. -* `DELETE`: для видалення даних. +* `POST`: щоб створити дані. +* `GET`: щоб читати дані. +* `PUT`: щоб оновити дані. +* `DELETE`: щоб видалити дані. -В OpenAPI кожен HTTP метод називається "операція". +Отже, в OpenAPI кожен з HTTP методів називається «операцією». -Ми також будемо дотримуватися цього терміна. +Ми також будемо називати їх «**операціями**». -#### Визначте декоратор операції шляху (path operation decorator) +#### Визначте *декоратор операції шляху* { #define-a-path-operation-decorator } -{* ../../docs_src/first_steps/tutorial001.py hl[6] *} -Декоратор `@app.get("/")` вказує **FastAPI**, що функція нижче, відповідає за обробку запитів, які надходять до неї: +{* ../../docs_src/first_steps/tutorial001_py39.py hl[6] *} -* шлях `/` +Декоратор `@app.get("/")` повідомляє **FastAPI**, що функція одразу нижче відповідає за обробку запитів, які надходять до: + +* шляху `/` * використовуючи get операцію -/// info | `@decorator` Додаткова інформація +/// info | `@decorator` Інформація -Синтаксис `@something` у Python називається "декоратором". +Синтаксис `@something` у Python називається «декоратором». Ви розташовуєте його над функцією. Як гарний декоративний капелюх (мабуть, звідти походить термін). -"Декоратор" приймає функцію нижче і виконує з нею якусь дію. +«Декоратор» бере функцію нижче і виконує з нею якусь дію. У нашому випадку, цей декоратор повідомляє **FastAPI**, що функція нижче відповідає **шляху** `/` і **операції** `get`. -Це і є "декоратор операції шляху (path operation decorator)". +Це і є «**декоратор операції шляху**». /// -Можна також використовувати операції: +Можна також використовувати інші операції: * `@app.post()` * `@app.put()` @@ -271,58 +302,79 @@ https://example.com/items/foo /// tip | Порада -Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд. +Ви можете використовувати кожну операцію (HTTP-метод) як забажаєте. -**FastAPI** не нав'язує жодного певного значення для кожного методу. +**FastAPI** не навʼязує жодного конкретного значення. -Наведена тут інформація є рекомендацією, а не обов'язковою вимогою. +Наведена тут інформація подана як настанова, а не вимога. -Наприклад, під час використання GraphQL зазвичай усі дії виконуються тільки за допомогою `POST` операцій. +Наприклад, під час використання GraphQL ви зазвичай виконуєте всі дії, використовуючи лише `POST` операції. /// -### Крок 4: визначте **функцію операції шляху (path operation function)** +### Крок 4: визначте **функцію операції шляху** { #step-4-define-the-path-operation-function } -Ось "**функція операції шляху**": +Ось наша «**функція операції шляху**»: * **шлях**: це `/`. * **операція**: це `get`. -* **функція**: це функція, яка знаходиться нижче "декоратора" (нижче `@app.get("/")`). +* **функція**: це функція нижче «декоратора» (нижче `@app.get("/")`). -{* ../../docs_src/first_steps/tutorial001.py hl[7] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *} -Це звичайна функція Python. +Це функція Python. -FastAPI викликатиме її щоразу, коли отримає запит до URL із шляхом "/", використовуючи операцію `GET`. +**FastAPI** викликатиме її щоразу, коли отримає запит до URL «`/`», використовуючи операцію `GET`. -У даному випадку це асинхронна функція. +У цьому випадку це `async` функція. --- Ви також можете визначити її як звичайну функцію замість `async def`: -{* ../../docs_src/first_steps/tutorial003.py hl[7] *} +{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *} /// note | Примітка -Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}. +Якщо ви не знаєте різницю, подивіться [Асинхронність: *«Поспішаєте?»*](../async.md#in-a-hurry){.internal-link target=_blank}. /// -### Крок 5: поверніть результат +### Крок 5: поверніть вміст { #step-5-return-the-content } -{* ../../docs_src/first_steps/tutorial001.py hl[8] *} +{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *} -Ви можете повернути `dict`, `list`, а також окремі значення `str`, `int`, ітд. +Ви можете повернути `dict`, `list`, а також окремі значення `str`, `int` тощо. Також можна повернути моделі Pydantic (про це ви дізнаєтесь пізніше). -Існує багато інших об'єктів і моделей, які будуть автоматично конвертовані в JSON (зокрема ORM тощо). Спробуйте використати свої улюблені, велика ймовірність, що вони вже підтримуються. +Існує багато інших обʼєктів і моделей, які будуть автоматично конвертовані в JSON (зокрема ORM тощо). Спробуйте використати свої улюблені — велика ймовірність, що вони вже підтримуються. + +### Крок 6: розгорніть його { #step-6-deploy-it } + +Розгорніть ваш застосунок у **FastAPI Cloud** однією командою: `fastapi deploy`. 🎉 + +#### Про FastAPI Cloud { #about-fastapi-cloud } + +**FastAPI Cloud** створено тим самим автором і командою, які стоять за **FastAPI**. + +Він спрощує процес **створення**, **розгортання** та **доступу** до API з мінімальними зусиллями. + +Він переносить той самий **досвід розробника** зі створення застосунків на FastAPI на **розгортання** їх у хмарі. 🎉 + +FastAPI Cloud — основний спонсор і джерело фінансування для open source проєктів *FastAPI and friends*. ✨ + +#### Розгортання в інших хмарних провайдерах { #deploy-to-other-cloud-providers } + +FastAPI — це open source і базується на стандартах. Ви можете розгортати FastAPI-застосунки у будь-якого хмарного провайдера на ваш вибір. + +Дотримуйтеся інструкцій вашого хмарного провайдера, щоб розгорнути FastAPI-застосунки з їхньою допомогою. 🤓 -## Підіб'ємо підсумки +## Підібʼємо підсумки { #recap } -* Імпортуємо `FastAPI`. -* Створюємо екземпляр `app`. -* Пишемо **декоратор операції шляху** як `@app.get("/")`. -* Пишемо **функцію операції шляху**; наприклад, `def root(): ...`. -* Запускаємо сервер у режимі розробки `fastapi dev`. +* Імпортуйте `FastAPI`. +* Створіть екземпляр `app`. +* Напишіть **декоратор операції шляху**, використовуючи декоратори на кшталт `@app.get("/")`. +* Визначте **функцію операції шляху**; наприклад, `def root(): ...`. +* Запустіть сервер розробки командою `fastapi dev`. +* За бажанням розгорніть ваш застосунок за допомогою `fastapi deploy`. diff --git a/docs/uk/docs/tutorial/handling-errors.md b/docs/uk/docs/tutorial/handling-errors.md index 32de73b2a0..53b8b12f61 100644 --- a/docs/uk/docs/tutorial/handling-errors.md +++ b/docs/uk/docs/tutorial/handling-errors.md @@ -1,10 +1,10 @@ -# Обробка Помилок +# Обробка помилок { #handling-errors } -Є багато ситуацій, коли потрібно повідомити клієнта, який використовує Ваш API, про помилку. +Є багато ситуацій, коли вам потрібно повідомити про помилку клієнта, який використовує ваш API. Цим клієнтом може бути браузер із фронтендом, код іншого розробника, IoT-пристрій тощо. -Можливо, Вам потрібно повідомити клієнта, що: +Можливо, вам потрібно повідомити клієнта, що: * У нього недостатньо прав для виконання цієї операції. * Він не має доступу до цього ресурсу. @@ -13,37 +13,37 @@ У таких випадках зазвичай повертається **HTTP статус-код** в діапазоні **400** (від 400 до 499). -Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці "200" статус-коди означають, що запит пройшов успішно. +Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці «200» статус-коди означають, що якимось чином запит був «успішним». Статус-коди в діапазоні 400 означають, що сталася помилка з боку клієнта. -Пам'ятаєте всі ці помилки **404 Not Found** (і жарти про них)? +Пам'ятаєте всі ці помилки **«404 Not Found»** (і жарти про них)? -## Використання `HTTPException` +## Використання `HTTPException` { #use-httpexception } Щоб повернути HTTP-відповіді з помилками клієнту, використовуйте `HTTPException`. -### Імпорт `HTTPException` +### Імпорт `HTTPException` { #import-httpexception } -{* ../../docs_src/handling_errors/tutorial001.py hl[1] *} +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *} -### Використання `HTTPException` у коді +### Згенеруйте `HTTPException` у своєму коді { #raise-an-httpexception-in-your-code } `HTTPException` — це звичайна помилка Python із додатковими даними, які стосуються API. -Оскільки це помилка Python, Ви не `повертаєте` його, а `генеруєте` (генеруєте помилку). +Оскільки це помилка Python, ви не `return` її, а `raise` її. -Це також означає, що якщо Ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там генеруєте `HTTPException`, всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту. +Це також означає, що якщо ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там згенеруєте `HTTPException` всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту. -Перевага використання `генерації` (raise) помилки замість `повернення` значення (return) стане більш очевидним в розділі про Залежності та Безпеку. +Перевага генерації виключення замість повернення значення стане більш очевидною в розділі про залежності та безпеку. -У цьому прикладі, якщо клієнт запитує елемент за ID, якого не існує, буде згенеровано помилку зі статус-кодом `404`: +У цьому прикладі, коли клієнт запитує елемент за ID, якого не існує, згенеруйте виключення зі статус-кодом `404`: -{* ../../docs_src/handling_errors/tutorial001.py hl[11] *} +{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *} -### Отримана відповідь +### Отримана відповідь { #the-resulting-response } -Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає статус-код 200 і JSON відповідь: +Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає HTTP статус-код 200 і JSON відповідь: ```JSON { @@ -51,7 +51,7 @@ } ``` -Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає статус-код 404 (помилка "не знайдено") та відповідь: +Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає HTTP статус-код 404 (помилка «не знайдено») та JSON відповідь: ```JSON { @@ -61,7 +61,7 @@ /// tip | Порада -Під час виклику `HTTPException` Ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише рядок (`str`). +Під час генерації `HTTPException` ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише `str`. Ви можете передати `dict`, `list` тощо. @@ -69,33 +69,33 @@ /// -## Додавання власних заголовків +## Додавання власних заголовків { #add-custom-headers } -Іноді потрібно додати власні заголовки до HTTP-помилки, наприклад, для певних типів безпеки. +Є деякі ситуації, коли корисно мати можливість додавати власні заголовки до HTTP-помилки. Наприклад, для деяких типів безпеки. -Ймовірно, Вам не доведеться використовувати це безпосередньо у своєму коді. +Ймовірно, вам не доведеться використовувати це безпосередньо у своєму коді. -Але якщо Вам знадобиться це для складного сценарію, Ви можете додати власні заголовки: +Але якщо вам знадобиться це для складного сценарію, ви можете додати власні заголовки: -{* ../../docs_src/handling_errors/tutorial002.py hl[14] *} +{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *} -## Встановлення власних обробників помилок +## Встановлення власних обробників виключень { #install-custom-exception-handlers } -Ви можете додати власні обробники помилок за допомогою тих самих утиліт обробки помилок зі Starlette. +Ви можете додати власні обробники виключень за допомогою тих самих утиліт для виключень зі Starlette. -Припустимо, у Вас є власний обʼєкт помилки `UnicornException`, яке Ви (або бібліотека, яку Ви використовуєте) може `згенерувати` (`raise`). +Припустімо, у вас є власне виключення `UnicornException`, яке ви (або бібліотека, яку ви використовуєте) можете `raise`. -І Ви хочете обробляти це виключення глобально за допомогою FastAPI. +І ви хочете обробляти це виключення глобально за допомогою FastAPI. Ви можете додати власний обробник виключень за допомогою `@app.exception_handler()`: -{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *} +{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *} -Тут, якщо Ви звернетеся до `/unicorns/yolo`, то згенерується помилка `UnicornException`. +Тут, якщо ви звернетеся до `/unicorns/yolo`, *операція шляху* згенерує (`raise`) `UnicornException`. Але вона буде оброблена функцією-обробником `unicorn_exception_handler`. -Отже, Ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-відповіддю: +Отже, ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-вмістом: ```JSON {"message": "Oops! yolo did something. There goes a rainbow..."} @@ -105,31 +105,31 @@ Ви також можете використовувати `from starlette.requests import Request` і `from starlette.responses import JSONResponse`. -**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме стосується і `Request`. +**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме з `Request`. /// -## Перевизначення обробників помилок за замовчуванням +## Перевизначення обробників виключень за замовчуванням { #override-the-default-exception-handlers } -**FastAPI** має кілька обробників помилок за замовчуванням. +**FastAPI** має кілька обробників виключень за замовчуванням. -Ці обробники відповідають за повернення стандартних JSON-відповідей, коли Ви `генеруєте` (`raise`) `HTTPException`, а також коли запит містить некоректні дані. +Ці обробники відповідають за повернення стандартних JSON-відповідей, коли ви `raise` `HTTPException`, а також коли запит містить некоректні дані. -Ви можете перевизначити ці обробники, створивши власні. +Ви можете перевизначити ці обробники виключень власними. -### Перевизначення помилок валідації запиту +### Перевизначення виключень валідації запиту { #override-request-validation-exceptions } -Коли запит містить некоректні дані, **FastAPI** генерує `RequestValidationError`. +Коли запит містить некоректні дані, **FastAPI** внутрішньо генерує `RequestValidationError`. -І також включає обробник помилок за замовчуванням для нього. +І також включає обробник виключень за замовчуванням для нього. -Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника помилок. +Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника виключень. -Обробник помилок отримує `Request` і саму помилку. +Обробник виключень отримає `Request` і саме виключення. -{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *} +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *} -Тепер, якщо Ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку: +Тепер, якщо ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку: ```JSON { @@ -146,55 +146,44 @@ } ``` -Ви отримаєте текстову версію: +ви отримаєте текстову версію: ``` -1 validation error -path -> item_id - value is not a valid integer (type=type_error.integer) +Validation errors: +Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer ``` -#### `RequestValidationError` проти `ValidationError` +### Перевизначення обробника помилок `HTTPException` { #override-the-httpexception-error-handler } -/// warning | Увага +Аналогічно, ви можете перевизначити обробник `HTTPException`. -Це технічні деталі, які Ви можете пропустити, якщо вони зараз не важливі для Вас. +Наприклад, ви можете захотіти повернути відповідь у вигляді простого тексту замість JSON для цих помилок: -/// - -`RequestValidationError` є підкласом Pydantic `ValidationError`. - -**FastAPI** використовує його для того, якщо Ви використовуєте модель Pydantic у `response_model` і у ваших даних є помилка, Ви побачили помилку у своєму журналі. - -Але клієнт/користувач не побачить її. Натомість клієнт отримає "Internal Server Error" зі статусом HTTP `500`. - -Так має бути, якщо у Вас виникла `ValidationError` Pydantic у *відповіді* або деінде у вашому коді (не у *запиті* клієнта), це насправді є помилкою у Вашому коді. - -І поки Ви її виправляєте, клієнти/користувачі не повинні мати доступу до внутрішньої інформації про помилку, оскільки це може призвести до вразливості безпеки. +{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *} -### Перевизначення обробника помилок `HTTPException` +/// note | Технічні деталі -Аналогічно, Ви можете перевизначити обробник `HTTPException`. +Ви також можете використовувати `from starlette.responses import PlainTextResponse`. -Наприклад, Ви можете захотіти повернути текстову відповідь замість JSON для цих помилок: +**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. -{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *} +/// -/// note | Технічні деталі +/// warning | Попередження -Ви також можете використовувати `from starlette.responses import PlainTextResponse`. +Пам’ятайте, що `RequestValidationError` містить інформацію про назву файлу та рядок, де сталася помилка валідації, щоб за потреби ви могли показати це у своїх логах із відповідною інформацією. -**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. +Але це означає, що якщо ви просто перетворите це на рядок і повернете цю інформацію напряму, ви можете розкрити трохи інформації про вашу систему, тому тут код витягає та показує кожну помилку незалежно. /// -### Використання тіла `RequestValidationError` +### Використання тіла `RequestValidationError` { #use-the-requestvalidationerror-body } `RequestValidationError` містить `body`, який він отримав із некоректними даними. Ви можете використовувати це під час розробки свого додатка, щоб логувати тіло запиту та налагоджувати його, повертати користувачеві тощо. -{* ../../docs_src/handling_errors/tutorial005.py hl[14] *} +{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *} Тепер спробуйте надіслати некоректний елемент, наприклад: @@ -204,8 +193,8 @@ path -> item_id "size": "XL" } ``` -Ви отримаєте відповідь, яка повідомить Вам, які саме дані є некоректні у вашому тілі запиту: +Ви отримаєте відповідь, яка повідомить вам, що дані є некоректними, і міститиме отримане тіло запиту: ```JSON hl_lines="12-15" { @@ -226,30 +215,30 @@ path -> item_id } ``` -#### `HTTPException` FastAPI проти `HTTPException` Starlette +#### `HTTPException` FastAPI проти `HTTPException` Starlette { #fastapis-httpexception-vs-starlettes-httpexception } **FastAPI** має власний `HTTPException`. -І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` в Starlette. +І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` у Starlette. Єдина різниця полягає в тому, що `HTTPException` в **FastAPI** приймає будь-які дані, які можна перетворити на JSON, для поля `detail`, тоді як `HTTPException` у Starlette приймає тільки рядки. -Отже, Ви можете продовжувати використовувати `HTTPException` в **FastAPI** як зазвичай у своєму коді. +Отже, ви можете продовжувати генерувати `HTTPException` **FastAPI** як зазвичай у своєму коді. -Але коли Ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette. +Але коли ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette. -Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує (raise) `HTTPException`, Ваш обробник зможе перехопити та обробити її. +Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує Starlette `HTTPException`, ваш обробник зможе перехопити та обробити її. -У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, помилка Starlette перейменовується на `StarletteHTTPException`: +У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, виключення Starlette перейменовується на `StarletteHTTPException`: ```Python from starlette.exceptions import HTTPException as StarletteHTTPException ``` -### Повторне використання обробників помилок **FastAPI** +### Повторне використання обробників виключень **FastAPI** { #reuse-fastapis-exception-handlers } -Якщо Ви хочете використовувати помилки разом із такими ж обробниками помилок за замовчуванням, як у **FastAPI**, Ви можете імпортувати та повторно використовувати їх із `fastapi.exception_handlers`: +Якщо ви хочете використовувати виключення разом із такими ж обробниками виключень за замовчуванням, як у **FastAPI**, ви можете імпортувати та повторно використати обробники виключень за замовчуванням із `fastapi.exception_handlers`: -{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *} +{* ../../docs_src/handling_errors/tutorial006_py39.py hl[2:5,15,21] *} -У цьому прикладі Ви просто використовуєте `print` для виведення дуже інформативного повідомлення, але Ви зрозуміли основну ідею. Ви можете обробити помилку та повторно використовувати обробники помилок за замовчуванням. +У цьому прикладі ви просто друкуєте помилку з дуже виразним повідомленням, але ви зрозуміли основну ідею. Ви можете використовувати виключення, а потім просто повторно використати обробники виключень за замовчуванням. diff --git a/docs/uk/docs/tutorial/header-param-models.md b/docs/uk/docs/tutorial/header-param-models.md index 6f7b0bdae7..c080c19f06 100644 --- a/docs/uk/docs/tutorial/header-param-models.md +++ b/docs/uk/docs/tutorial/header-param-models.md @@ -1,26 +1,24 @@ -# Моделі Параметрів Заголовків +# Моделі параметрів заголовків { #header-parameter-models } -Якщо у Вас є група пов’язаних параметрів заголовків, Ви можете створити **Pydantic модель** для їх оголошення. +Якщо у Вас є група пов’язаних **параметрів заголовків**, Ви можете створити **Pydantic модель** для їх оголошення. Це дозволить Вам повторно **використовувати модель** в **різних місцях**, а також оголосити валідації та метадані для всіх параметрів одночасно. 😎 -/// note | Нотатки +/// note | Примітка Ця можливість підтримується починаючи з версії FastAPI `0.115.0`. 🤓 /// -## Параметри Заголовків з Використанням Pydantic Model +## Параметри заголовків з використанням Pydantic моделі { #header-parameters-with-a-pydantic-model } Оголосіть потрібні **параметри заголовків** у **Pydantic моделі**, а потім оголосіть параметр як `Header`: {* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *} -FastAPI буде витягувати дані для кожного поля з заголовків у запиті та передавати їх у створену Вами Pydantic модель. - **FastAPI** буде **витягувати** дані для **кожного поля** з **заголовків** у запиті та передавати їх у створену Вами Pydantic модель. -## Перевірка в Документації +## Перевірка в документації { #check-the-docs } Ви можете побачити необхідні заголовки в інтерфейсі документації за адресою `/docs`: @@ -28,7 +26,7 @@ FastAPI буде витягувати дані для кожного поля з
-## Заборона Додаткових Заголовків +## Заборонити додаткові заголовки { #forbid-extra-headers } У деяких особливих випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** заголовки, які хочете отримати. @@ -38,7 +36,7 @@ FastAPI буде витягувати дані для кожного поля з Якщо клієнт спробує надіслати **додаткові заголовки**, він отримає **помилку** у відповіді. -Наприклад, якщо клієнт спробує надіслати заголовок `tool` зі значенням `plumbus`, він отримає **помилку** з повідомленням про те, що параметр заголовка `tool` не дозволений: +Наприклад, якщо клієнт спробує надіслати заголовок `tool` зі значенням `plumbus`, він отримає **помилку** у відповіді з повідомленням про те, що параметр заголовка `tool` не дозволений: ```json { @@ -53,6 +51,22 @@ FastAPI буде витягувати дані для кожного поля з } ``` -## Підсумок +## Вимкнути перетворення підкреслень { #disable-convert-underscores } + +Так само, як і зі звичайними параметрами заголовків, коли у назвах параметрів є символи підкреслення, вони **автоматично перетворюються на дефіси**. + +Наприклад, якщо у коді у Вас є параметр заголовка `save_data`, очікуваний HTTP-заголовок буде `save-data`, і він так само відображатиметься в документації. + +Якщо з якоїсь причини Вам потрібно вимкнути це автоматичне перетворення, Ви також можете зробити це для Pydantic моделей для параметрів заголовків. + +{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *} + +/// warning | Попередження + +Перш ніж встановлювати `convert_underscores` у значення `False`, пам’ятайте, що деякі HTTP проксі та сервери забороняють використання заголовків із підкресленнями. + +/// + +## Підсумок { #summary } Ви можете використовувати **Pydantic моделі** для оголошення **заголовків** у **FastAPI**. 😎 diff --git a/docs/uk/docs/tutorial/header-params.md b/docs/uk/docs/tutorial/header-params.md index 09c70a4f61..f5a4ea18d1 100644 --- a/docs/uk/docs/tutorial/header-params.md +++ b/docs/uk/docs/tutorial/header-params.md @@ -1,14 +1,14 @@ -# Header-параметри +# Параметри заголовків { #header-parameters } -Ви можете визначати параметри заголовків, так само як визначаєте `Query`, `Path` і `Cookie` параметри. +Ви можете визначати параметри заголовків так само, як визначаєте параметри `Query`, `Path` і `Cookie`. -## Імпорт `Header` +## Імпорт `Header` { #import-header } Спочатку імпортуйте `Header`: {* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *} -## Оголошення параметрів `Header` +## Оголошення параметрів `Header` { #declare-header-parameters } Потім оголосіть параметри заголовків, використовуючи ту ж структуру, що й для `Path`, `Query` та `Cookie`. @@ -18,9 +18,9 @@ /// note | Технічні деталі -`Header`є "сестринським" класом для `Path`, `Query` і `Cookie`. Він також успадковується від загального класу `Param`. +`Header` є «сестринським» класом для `Path`, `Query` і `Cookie`. Він також успадковується від того ж спільного класу `Param`. -Але пам’ятайте, що при імпорті `Query`, `Path`, `Header` та інших із `fastapi`, то насправді вони є функціями, які повертають спеціальні класи. +Але пам’ятайте, що коли ви імпортуєте `Query`, `Path`, `Header` та інші з `fastapi`, то насправді це функції, які повертають спеціальні класи. /// @@ -30,43 +30,43 @@ /// -## Автоматичне перетворення +## Автоматичне перетворення { #automatic-conversion } -`Header` має додатковий функціонал порівняно з `Path`, `Query` та `Cookie`. +`Header` має трохи додаткової функціональності порівняно з тим, що надають `Path`, `Query` та `Cookie`. -Більшість стандартних заголовків розділяються символом «дефіс», також відомим як «мінус» (`-`). +Більшість стандартних заголовків розділяються символом «дефіс», також відомим як «символ мінуса» (`-`). Але змінна, така як `user-agent`, є недійсною в Python. -Тому, за замовчуванням, `Header` автоматично перетворює символи підкреслення (`_`) на дефіси (`-`) для отримання та документування заголовків. +Тому, за замовчуванням, `Header` перетворюватиме символи підкреслення (`_`) у назвах параметрів на дефіси (`-`), щоб отримувати та документувати заголовки. -Оскільки заголовки HTTP не чутливі до регістру, Ви можете використовувати стандартний стиль Python ("snake_case"). +Також заголовки HTTP не чутливі до регістру, тож ви можете оголошувати їх у стандартному стилі Python (також відомому як «snake_case»). -Тому Ви можете використовувати `user_agent`, як зазвичай у коді Python, замість того щоб писати з великої літери, як `User_Agent` або щось подібне. +Тому ви можете використовувати `user_agent`, як зазвичай у коді Python, замість того щоб потрібно було писати з великої літери перші літери, як `User_Agent` або щось подібне. -Якщо Вам потрібно вимкнути автоматичне перетворення підкреслень у дефіси, встановіть `convert_underscores` в `Header` значення `False`: +Якщо з якоїсь причини вам потрібно вимкнути автоматичне перетворення підкреслень на дефіси, встановіть параметр `convert_underscores` у `Header` в `False`: {* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *} -/// warning | Увага +/// warning | Попередження -Перед тим як встановити значення `False` для `convert_underscores` пам’ятайте, що деякі HTTP-проксі та сервери не підтримують заголовки з підкресленнями. +Перед тим як встановити `convert_underscores` в `False`, пам’ятайте, що деякі HTTP-проксі та сервери забороняють використання заголовків із підкресленнями. /// -## Дубльовані заголовки +## Дубльовані заголовки { #duplicate-headers } -Можливо отримати дубльовані заголовки, тобто той самий заголовок із кількома значеннями. +Можливо отримати дубльовані заголовки. Тобто один і той самий заголовок із кількома значеннями. -Це можна визначити, використовуючи список у типізації параметра. +Ви можете визначити такі випадки, використовуючи список у типізації. -Ви отримаєте всі значення дубльованого заголовка у вигляді `list` у Python. +Ви отримаєте всі значення дубльованого заголовка у вигляді Python-`list`. -Наприклад, щоб оголосити заголовок `X-Token`, який може з’являтися більше ніж один раз: +Наприклад, щоб оголосити заголовок `X-Token`, який може з’являтися більше ніж один раз, ви можете написати: {* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *} -Якщо Ви взаємодієте з цією операцією шляху, надсилаючи два HTTP-заголовки, наприклад: +Якщо ви взаємодієте з цією *операцією шляху*, надсилаючи два HTTP-заголовки, наприклад: ``` X-Token: foo @@ -84,8 +84,8 @@ X-Token: bar } ``` -## Підсумок +## Підсумок { #recap } -Оголошуйте заголовки за допомогою `Header`, використовуючи той самий підхід, що й для `Query`, `Path` та `Cookie`. +Оголошуйте заголовки за допомогою `Header`, використовуючи той самий загальний підхід, що й для `Query`, `Path` та `Cookie`. -Не хвилюйтеся про підкреслення у змінних — **FastAPI** автоматично конвертує їх. +І не хвилюйтеся про підкреслення у ваших змінних — **FastAPI** подбає про їх перетворення. diff --git a/docs/uk/docs/tutorial/index.md b/docs/uk/docs/tutorial/index.md index 92c3e77a36..6848090ecc 100644 --- a/docs/uk/docs/tutorial/index.md +++ b/docs/uk/docs/tutorial/index.md @@ -1,29 +1,53 @@ -# Туторіал - Посібник користувача +# Туторіал - Посібник користувача { #tutorial-user-guide } У цьому посібнику показано, як користуватися **FastAPI** з більшістю його функцій, крок за кроком. Кожен розділ поступово надбудовується на попередні, але він структурований на окремі теми, щоб ви могли перейти безпосередньо до будь-якої конкретної, щоб вирішити ваші конкретні потреби API. -Він також створений як довідник для роботи у майбутньому. +Також він створений як довідник для роботи у майбутньому, тож ви можете повернутися і побачити саме те, що вам потрібно. -Тож ви можете повернутися і побачити саме те, що вам потрібно. - -## Запустіть код +## Запустіть код { #run-the-code } Усі блоки коду можна скопіювати та використовувати безпосередньо (це фактично перевірені файли Python). -Щоб запустити будь-який із прикладів, скопіюйте код у файл `main.py` і запустіть `uvicorn` за допомогою: +Щоб запустити будь-який із прикладів, скопіюйте код у файл `main.py` і запустіть `fastapi dev` за допомогою:
```console -$ uvicorn main:app --reload +$ fastapi dev main.py + + FastAPI Starting development server 🚀 + + Searching for package file structure from directories + with __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with + the following code: + + from main import app + + app Using import string: main:app + + server Server started at http://127.0.0.1:8000 + server Documentation at http://127.0.0.1:8000/docs + + tip Running in development mode, for production use: + fastapi run -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -INFO: Started reloader process [28720] -INFO: Started server process [28722] -INFO: Waiting for application startup. -INFO: Application startup complete. + Logs: + + INFO Will watch for changes in these directories: + ['/home/user/code/awesomeapp'] + INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C + to quit) + INFO Started reloader process [383138] using WatchFiles + INFO Started server process [383153] + INFO Waiting for application startup. + INFO Application startup complete. ```
@@ -34,45 +58,33 @@ $ uvicorn main:app --reload --- -## Встановлення FastAPI +## Встановлення FastAPI { #install-fastapi } Першим кроком є встановлення FastAPI. -Для туторіалу ви можете встановити його з усіма необов’язковими залежностями та функціями: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім **встановіть FastAPI**:
```console -$ pip install "fastapi[all]" +$ pip install "fastapi[standard]" ---> 100% ```
-...який також включає `uvicorn`, який ви можете використовувати як сервер, який запускає ваш код. - -/// note - -Ви також можете встановити його частина за частиною. +/// note | Примітка -Це те, що ви, ймовірно, зробили б, коли захочете розгорнути свою програму у виробничому середовищі: +Коли ви встановлюєте через `pip install "fastapi[standard]"`, він постачається з деякими типовими необов’язковими стандартними залежностями, включно з `fastapi-cloud-cli`, який дозволяє розгортати в FastAPI Cloud. -``` -pip install fastapi -``` - -Також встановіть `uvicorn`, щоб він працював як сервер: - -``` -pip install "uvicorn[standard]" -``` +Якщо ви не хочете мати ці необов’язкові залежності, натомість можете встановити `pip install fastapi`. -І те саме для кожної з опціональних залежностей, які ви хочете використовувати. +Якщо ви хочете встановити стандартні залежності, але без `fastapi-cloud-cli`, ви можете встановити через `pip install "fastapi[standard-no-fastapi-cloud-cli]"`. /// -## Розширений посібник користувача +## Розширений посібник користувача { #advanced-user-guide } Існує також **Розширений посібник користувача**, який ви зможете прочитати пізніше після цього **Туторіал - Посібник користувача**. @@ -80,4 +92,4 @@ pip install "uvicorn[standard]" Але вам слід спочатку прочитати **Туторіал - Посібник користувача** (те, що ви зараз читаєте). -Він розроблений таким чином, що ви можете створити повну програму лише за допомогою **Туторіал - Посібник користувача**, а потім розширити її різними способами, залежно від ваших потреб, використовуючи деякі з додаткових ідей з **Розширеного посібника користувача** . +Він розроблений таким чином, що ви можете створити повну програму лише за допомогою **Туторіал - Посібник користувача**, а потім розширити її різними способами, залежно від ваших потреб, використовуючи деякі з додаткових ідей з **Розширеного посібника користувача**. diff --git a/docs/uk/docs/tutorial/metadata.md b/docs/uk/docs/tutorial/metadata.md index 64e667ec69..cf17045628 100644 --- a/docs/uk/docs/tutorial/metadata.md +++ b/docs/uk/docs/tutorial/metadata.md @@ -1,26 +1,26 @@ -# Метадані та URL-адреси документації +# Метадані та URL-адреси документації { #metadata-and-docs-urls } Ви можете налаштувати кілька конфігурацій метаданих у Вашому додатку **FastAPI**. -## Метадані для API +## Метадані для API { #metadata-for-api } Ви можете встановити такі поля, які використовуються в специфікації OpenAPI та в автоматично згенерованих інтерфейсах документації API: | Параметр | Тип | Опис | |------------|------|-------------| | `title` | `str` | Назва API. | -| `summary` | `str` | Короткий опис API. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0. | -| `description` | `str` | Більш детальний опис API. Може використовувати Markdown. | +| `summary` | `str` | Короткий підсумок API. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0. | +| `description` | `str` | Короткий опис API. Може використовувати Markdown. | | `version` | `string` | Версія API. Це версія Вашого додатка, а не OpenAPI. Наприклад, `2.5.0`. | -| `terms_of_service` | `str` | URL до умов використання API. Якщо вказано, має бути у форматі URL. | -| `contact` | `dict` | Інформація для контакту з API. Може містити кілька полів.
contact поля
ПараметрТипОпис
namestrІм'я контактної особи або організації.
urlstrURL з інформацією для контакту. Повинен бути у форматі URL.
emailstrEmail контактної особи або організації. Повинен бути у форматі електронної пошти.
| -| `license_info` | `dict` | Інформація про ліцензію для API. Може містити кілька полів.
license_info поля
ПараметрТипОпис
namestrОБОВ'ЯЗКОВО (якщо встановлено license_info). Назва ліцензії для API.
identifierstrЛіцензійний вираз за SPDX для API. Поле identifier взаємовиключне з полем url. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.
urlstrURL до ліцензії, яка використовується для API. Повинен бути у форматі URL.
| +| `terms_of_service` | `str` | URL до умов використання API. Якщо вказано, має бути у форматі URL. | +| `contact` | `dict` | Інформація для контакту з опублікованим API. Може містити кілька полів.
contact поля
ПараметрТипОпис
namestrІдентифікаційне ім'я контактної особи або організації.
urlstrURL, що вказує на контактну інформацію. МАЄ бути у форматі URL.
emailstrАдреса електронної пошти контактної особи або організації. МАЄ бути у форматі адреси електронної пошти.
| +| `license_info` | `dict` | Інформація про ліцензію для опублікованого API. Може містити кілька полів.
license_info поля
ПараметрТипОпис
namestrОБОВ'ЯЗКОВО (якщо встановлено license_info). Назва ліцензії для API.
identifierstrЛіцензійний вираз за SPDX для API. Поле identifier взаємовиключне з полем url. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.
urlstrURL до ліцензії, яка використовується для API. МАЄ бути у форматі URL.
| Ви можете налаштувати їх наступним чином: -{* ../../docs_src/metadata/tutorial001.py hl[3:16, 19:32] *} +{* ../../docs_src/metadata/tutorial001_py39.py hl[3:16, 19:32] *} -/// tip | Підказка +/// tip | Порада У полі `description` можна використовувати Markdown, і він буде відображатися у результаті. @@ -30,15 +30,15 @@ -## Ідентифікатор ліцензії +## Ідентифікатор ліцензії { #license-identifier } З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати `license_info` за допомогою `identifier` замість `url`. Наприклад: -{* ../../docs_src/metadata/tutorial001_1.py hl[31] *} +{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *} -## Метадані для тегів +## Метадані для тегів { #metadata-for-tags } Ви також можете додати додаткові метадані для різних тегів, які використовуються для групування операцій шляхів, за допомогою параметра `openapi_tags`. @@ -46,53 +46,53 @@ Кожен словник може містити: -* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s. -* `description`: `str` з коротким описом тегу. Може містити Markdown і буде відображено в інтерфейсі документації. -* `externalDocs`: `dict` який описує зовнішню документацію з такими полями: +* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s. +* `description`: `str` з коротким описом тегу. Може містити Markdown і буде показано в інтерфейсі документації. +* `externalDocs`: `dict`, який описує зовнішню документацію з такими полями: * `description`: `str` з коротким описом зовнішньої документації. - * `url` (**обов'язково**): `str`з URL-адресою зовнішньої документації. + * `url` (**обов'язково**): `str` з URL-адресою зовнішньої документації. -### Створення метаданих для тегів +### Створення метаданих для тегів { #create-metadata-for-tags } Спробуймо це на прикладі з тегами для `users` та `items`. -Створіть метадані для своїх тегів і передайте їх у параметр `openapi_tags`: +Створіть метадані для своїх тегів і передайте їх у параметр `openapi_tags`: -{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *} +{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *} Зверніть увагу, що в описах можна використовувати Markdown, наприклад, "login" буде показано жирним шрифтом (**login**), а "fancy" буде показано курсивом (_fancy_). /// tip | Порада -Не обов'язково додавати метадані для всіх тегів, які Ви використовуєте. +Вам не потрібно додавати метадані для всіх тегів, які Ви використовуєте. /// -### Використання тегів +### Використовуйте свої теги { #use-your-tags } -Використовуйте параметр `tags` зі своїми *операціями шляху* (і `APIRouter`) для призначення їх до різних тегів: +Використовуйте параметр `tags` зі своїми *операціями шляху* (і `APIRouter`s), щоб призначити їх до різних тегів: -{* ../../docs_src/metadata/tutorial004.py hl[21,26] *} +{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *} /// info | Інформація -Детальніше про теги читайте в розділі [Конфігурація шляхів операцій](path-operation-configuration.md#tags){.internal-link target=_blank}. +Детальніше про теги читайте в розділі [Конфігурація операції шляху](path-operation-configuration.md#tags){.internal-link target=_blank}. /// -### Перевірка документації +### Перевірте документацію { #check-the-docs } -Якщо Ви зараз перевірите документацію, вона покаже всі додаткові метадані: +Тепер, якщо Ви перевірите документацію, вона покаже всі додаткові метадані: -### Порядок тегів +### Порядок тегів { #order-of-tags } Порядок кожного словника метаданих тегу також визначає порядок відображення в інтерфейсі документації. -Наприклад, хоча `users` мав би йти після `items` в алфавітному порядку, він відображається перед ними, оскільки ми додали його метадані як перший словник у списку. +Наприклад, хоча `users` мав би йти після `items` в алфавітному порядку, він відображається перед ними, оскільки ми додали їхні метадані як перший словник у списку. -## URL для OpenAPI +## URL для OpenAPI { #openapi-url } За замовчуванням схема OpenAPI надається за адресою `/openapi.json`. @@ -100,11 +100,11 @@ Наприклад, щоб налаштувати його на `/api/v1/openapi.json`: -{* ../../docs_src/metadata/tutorial002.py hl[3] *} +{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *} Якщо Ви хочете повністю вимкнути схему OpenAPI, Ви можете встановити `openapi_url=None`, це також вимкне інтерфейси документації, які її використовують. -## URL-адреси документації +## URL-адреси документації { #docs-urls } Ви можете налаштувати два інтерфейси користувача для документації, які включені: @@ -117,4 +117,4 @@ Наприклад, щоб налаштувати Swagger UI на `/documentation` і вимкнути ReDoc: -{* ../../docs_src/metadata/tutorial003.py hl[3] *} +{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *} diff --git a/docs/uk/docs/tutorial/middleware.md b/docs/uk/docs/tutorial/middleware.md index 13ce8573de..2d1580e49e 100644 --- a/docs/uk/docs/tutorial/middleware.md +++ b/docs/uk/docs/tutorial/middleware.md @@ -1,45 +1,43 @@ -# Middleware (Проміжний шар) +# Middleware { #middleware } -У **FastAPI** можна додавати middleware (проміжний шар). +У **FastAPI** можна додавати middleware. -"Middleware" — це функція, яка працює з кожним **запитом** перед його обробкою будь-якою конкретною *операцією шляху* (*path operation*), а також з кожною **відповіддю** перед її поверненням. +«Middleware» — це функція, яка працює з кожним **запитом** перед його обробкою будь-якою конкретною *операцією шляху*. А також з кожною **відповіддю** перед її поверненням. -* Middleware отримує кожен **запит**, що надходить до Вашого застосунку. -* Може виконати певні дії із цим **запитом** або запустити необхідний код. -* Далі передає **запит** для обробки основним застосунком (*операцією шляху*). -* Отримує **відповідь**, сформовану застосунком (*операцією шляху*). -* Може змінити цю **відповідь** або виконати додатковий код. -* Повертає **відповідь** клієнту. +* Вона отримує кожен **запит**, що надходить до вашого застосунку. +* Потім вона може виконати певні дії із цим **запитом** або запустити необхідний код. +* Далі вона передає **запит** для обробки рештою застосунку (якоюсь *операцією шляху*). +* Потім вона отримує **відповідь**, сформовану застосунком (якоюсь *операцією шляху*). +* Вона може виконати певні дії із цією **відповіддю** або запустити необхідний код. +* Потім вона повертає **відповідь**. /// note | Технічні деталі -Якщо у Вас є залежності з `yield`, код виходу виконається *після* middleware. +Якщо у вас є залежності з `yield`, код виходу виконається *після* middleware. -Якщо були заплановані фонові задачі (background tasks - розглянуто далі), вони виконаються *після* всіх middleware. +Якщо були заплановані фонові задачі (розглянуто в розділі [Background Tasks](background-tasks.md){.internal-link target=_blank}, ви побачите це пізніше), вони виконаються *після* всіх middleware. /// -## Створення middleware +## Створення middleware { #create-a-middleware } -Щоб створити middleware, Ви використовуєте декоратор `@app.middleware("http")` на функції. +Щоб створити middleware, ви використовуєте декоратор `@app.middleware("http")` над функцією. Функція middleware отримує: -* `Запит`. -* Функцію `call_next`, яка приймає `запит` як параметр. - * Ця функція передає `запит` відповідній *операції шляху*. - * Потім вона повертає `відповідь`, згенеровану цією *операцією шляху*. +* `request`. +* Функцію `call_next`, яка отримає `request` як параметр. + * Ця функція передасть `request` відповідній *операції шляху*. + * Потім вона поверне `response`, згенеровану відповідною *операцією шляху*. +* Потім ви можете додатково змінити `response` перед тим, як повернути її. -* Ви можете ще змінити `відповідь` перед тим, як повернути її. - - -{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *} +{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *} /// tip | Порада -Не забувайте, що власні заголовки можна додавати, використовуючи префікс 'X-'. +Пам’ятайте, що власні пропрієтарні заголовки можна додавати використовуючи префікс `X-`. -Але якщо у Вас є власні заголовки, які Ви хочете, щоб браузерний клієнт міг побачити, потрібно додати їх до Вашої конфігурації CORS (див. [CORS (Обмін ресурсами між різними джерелами)](cors.md){.internal-link target=_blank} за допомогою параметра `expose_headers`, описаного в документації Starlette по CORS. +Але якщо у вас є власні заголовки, які ви хочете, щоб клієнт у браузері міг побачити, потрібно додати їх до ваших конфігурацій CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) за допомогою параметра `expose_headers`, описаного в документації Starlette по CORS. /// @@ -47,28 +45,50 @@ Ви також можете використати `from starlette.requests import Request`. -**FastAPI** надає це для Вашої зручності як розробника. Але він походить безпосередньо зі Starlette. +**FastAPI** надає це для вашої зручності як розробника. Але воно походить безпосередньо зі Starlette. /// -### До і після `response`(`відповіді`) +### До і після `response` { #before-and-after-the-response } -Ви можете додати код, який буде виконуватися з `запитом` (`request`), до того, як його обробить будь-яка *операція шляху* (*path operation*). +Ви можете додати код, який буде виконуватися з `request`, до того, як його отримає будь-яка *операція шляху*. -Також Ви можете додати код, який буде виконуватися після того, як `відповідь` (`response`) буде згенеровано, перед тим як його повернути. +Також ви можете додати код, який буде виконуватися після того, як `response` буде згенеровано, перед тим як її повернути. -Наприклад, Ви можете додати власний заголовок `X-Process-Time`, який міститиме час у секундах, який витратився на обробку запиту та генерацію відповіді: +Наприклад, ви можете додати власний заголовок `X-Process-Time`, який міститиме час у секундах, який витратився на обробку запиту та генерацію відповіді: -{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *} +{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *} - -/// tip | Підказка +/// tip | Порада Тут ми використовуємо `time.perf_counter()` замість `time.time()` оскільки він може бути більш точним для таких випадків. 🤓 /// -## Інші middlewares +## Порядок виконання кількох middleware { #multiple-middleware-execution-order } + +Коли ви додаєте кілька middleware, використовуючи або декоратор `@app.middleware()` або метод `app.add_middleware()`, кожен новий middleware обгортає застосунок, утворюючи стек. Останній доданий middleware є *зовнішнім*, а перший — *внутрішнім*. + +На шляху запиту першим виконується *зовнішній* middleware. + +На шляху відповіді він виконується останнім. + +Наприклад: + +```Python +app.add_middleware(MiddlewareA) +app.add_middleware(MiddlewareB) +``` + +Це призводить до такого порядку виконання: + +* **Запит**: MiddlewareB → MiddlewareA → route + +* **Відповідь**: route → MiddlewareA → MiddlewareB + +Така поведінка стеку гарантує, що middleware виконуються у передбачуваному та керованому порядку. + +## Інші middlewares { #other-middlewares } Ви можете пізніше прочитати більше про інші middlewares в [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}. diff --git a/docs/uk/docs/tutorial/path-params-numeric-validations.md b/docs/uk/docs/tutorial/path-params-numeric-validations.md index 8ee4f480fe..f6aa920193 100644 --- a/docs/uk/docs/tutorial/path-params-numeric-validations.md +++ b/docs/uk/docs/tutorial/path-params-numeric-validations.md @@ -1,8 +1,8 @@ -# Path Параметри та валідація числових даних +# Параметри шляху та валідація числових даних { #path-parameters-and-numeric-validations } -Так само як Ви можете оголошувати додаткові перевірки та метадані для query параметрів за допомогою `Query`, Ви можете оголошувати той самий тип перевірок і метаданих для параметрів шляху за допомогою `Path`. +Так само як ви можете оголошувати додаткові перевірки та метадані для query параметрів за допомогою `Query`, ви можете оголошувати той самий тип перевірок і метаданих для параметрів шляху за допомогою `Path`. -## Імпорт Path +## Імпорт `Path` { #import-path } Спочатку імпортуйте `Path` з `fastapi` і імпортуйте `Annotated`: @@ -10,70 +10,69 @@ /// info | Інформація -FastAPI додав підтримку `Annotated` (і почав рекомендувати його використання) у версії 0.95.0. +FastAPI додав підтримку `Annotated` (і почав рекомендувати його використання) у версії 0.95.0. -Якщо у Вас стара версія, при спробі використати `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){.internal-link target=_blank} принаймні до версії 0.95.1 перед використанням `Annotated`. /// -## Оголошення метаданих +## Оголошення метаданих { #declare-metadata } Ви можете оголошувати всі ті ж параметри, що і для `Query`. -Наприклад, щоб оголосити значення метаданих `title` для параметра шляху `item_id`, Ви можете написати: +Наприклад, щоб оголосити значення метаданих `title` для параметра шляху `item_id`, ви можете написати: {* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *} /// note | Примітка -Параметр шляху завжди є обов’язковим, оскільки він має бути частиною шляху. Навіть якщо Ви оголосите його зі значенням `None` або встановите значення за замовчуванням — він все одно залишатиметься обов’язковим. +Параметр шляху завжди є обов’язковим, оскільки він має бути частиною шляху. Навіть якщо ви оголосите його зі значенням `None` або встановите значення за замовчуванням — це ні на що не вплине, він все одно завжди буде обов’язковим. /// -## Упорядковуйте параметри, як Вам потрібно +## Упорядковуйте параметри, як вам потрібно { #order-the-parameters-as-you-need } -/// tip | Підказка +/// tip | Порада -Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`. +Це, мабуть, не настільки важливо або необхідно, якщо ви використовуєте `Annotated`. /// -Припустимо, Ви хочете оголосити параметр запиту `q` як обов’язковий `str`. +Припустимо, ви хочете оголосити параметр запиту `q` як обов’язковий `str`. -І Вам не потрібно оголошувати нічого іншого для цього параметра, тому немає потреби використовувати `Query`. +І вам не потрібно оголошувати нічого іншого для цього параметра, тому вам насправді не потрібно використовувати `Query`. -Але Вам все одно потрібно використовувати `Path` для параметра шляху `item_id`. І з певних причин Ви не хочете використовувати `Annotated`. +Але вам все одно потрібно використовувати `Path` для параметра шляху `item_id`. І з певних причин ви не хочете використовувати `Annotated`. Python видасть помилку, якщо розмістити значення з "default" перед значенням, яке не має "default". -Але Ви можете змінити порядок і розмістити значення без значення за замовчуванням (параметр запиту `q`) першим. +Але ви можете змінити порядок і розмістити значення без значення за замовчуванням (параметр запиту `q`) першим. +Для **FastAPI** порядок не має значення. Він визначає параметри за їхніми іменами, типами та оголошеннями за замовчуванням (`Query`, `Path` тощо) і не звертає уваги на порядок. -Для **FastAPI** порядок не має значення. Він визначає параметри за їх іменами, типами та значеннями за замовчуванням (`Query`, `Path` тощо) і не звертає уваги на порядок. +Тому ви можете оголосити вашу функцію так: -Тому Ви можете оголосити Вашу функцію так: +{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *} -{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *} - -Але майте на увазі, що якщо Ви використовуєте `Annotated`, ця проблема не виникне, оскільки Ви не використовуєте значення за замовчуванням для параметрів `Query()` або `Path()`. +Але майте на увазі, що якщо ви використовуєте `Annotated`, цієї проблеми не буде, це не матиме значення, оскільки ви не використовуєте значення за замовчуванням параметрів функції для `Query()` або `Path()`. {* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *} -## Упорядковуйте параметри за потребою, хитрощі +## Упорядковуйте параметри, як вам потрібно: хитрощі { #order-the-parameters-as-you-need-tricks } -/// tip | Підказка +/// tip | Порада -Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`. +Це, мабуть, не настільки важливо або необхідно, якщо ви використовуєте `Annotated`. /// Ось **невелика хитрість**, яка може стати в пригоді, хоча вона рідко знадобиться. -Якщо Ви хочете: +Якщо ви хочете: -* оголосити параметр запиту `q` без використання `Query` або значення за замовчуванням +* оголосити параметр запиту `q` без `Query` і без жодного значення за замовчуванням * оголосити параметр шляху `item_id`, використовуючи `Path` * розмістити їх у різному порядку * не використовувати `Annotated` @@ -84,72 +83,72 @@ Python видасть помилку, якщо розмістити значен Python нічого не зробить із цією `*`, але розпізнає, що всі наступні параметри слід викликати як аргументи за ключовим словом (пари ключ-значення), також відомі як kwargs. Навіть якщо вони не мають значення за замовчуванням. -{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *} +{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *} -### Краще з `Annotated` +### Краще з `Annotated` { #better-with-annotated } -Майте на увазі, якщо Ви використовуєте `Annotated`, оскільки Ви не використовуєте значення за замовчуванням для параметрів функції, цієї проблеми не виникне, і, швидше за все, Вам не потрібно буде використовувати `*`. +Майте на увазі, що якщо ви використовуєте `Annotated`, оскільки ви не використовуєте значення за замовчуванням параметрів функції, цієї проблеми не буде, і, ймовірно, вам не потрібно буде використовувати `*`. {* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *} -## Валідація числових даних: більше або дорівнює +## Валідація числових даних: більше або дорівнює { #number-validations-greater-than-or-equal } -За допомогою `Query` і `Path` (та інших, які Ви побачите пізніше) можна оголошувати числові обмеження. +За допомогою `Query` і `Path` (та інших, які ви побачите пізніше) можна оголошувати числові обмеження. Тут, завдяки `ge=1`, `item_id` має бути цілим числом, яке "`g`reater than or `e`qual" (більше або дорівнює) `1`. {* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *} -## Валідація числових даних: більше ніж і менше або дорівнює +## Валідація числових даних: більше ніж і менше або дорівнює { #number-validations-greater-than-and-less-than-or-equal } Те саме застосовується до: -* `gt`: `g`reater `t`han (більше ніж) -* `le`: `l`ess than or `e`qual (менше або дорівнює) +* `gt`: `g`reater `t`han +* `le`: `l`ess than or `e`qual {* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *} -## Валідація числових даних: float, більше ніж і менше ніж +## Валідація числових даних: float, більше ніж і менше ніж { #number-validations-floats-greater-than-and-less-than } Валідація чисел також працює для значень типу `float`. -Ось де стає важливо мати можливість оголошувати gt, а не тільки ge. Це дозволяє, наприклад, вимагати, щоб значення було більше `0`, навіть якщо воно менше `1`. +Ось де стає важливо мати можливість оголошувати gt, а не тільки ge. Це дозволяє, наприклад, вимагати, щоб значення було більше `0`, навіть якщо воно менше `1`. Таким чином, значення `0.5` буде допустимим. Але `0.0` або `0` — ні. -Те саме стосується lt. +Те саме стосується lt. {* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *} -## Підсумок +## Підсумок { #recap } -За допомогою `Query`, `Path` (і інших параметрів, які Ви ще не бачили) можна оголошувати метадані та перевірки рядків, так само як у [Query параметри та валідація рядків](query-params-str-validations.md){.internal-link target=_blank}. +За допомогою `Query`, `Path` (і інших параметрів, які ви ще не бачили) можна оголошувати метадані та перевірки рядків так само як у [Query параметри та валідація рядків](query-params-str-validations.md){.internal-link target=_blank}. Також можна оголошувати числові перевірки: -* `gt`: `g`reater `t`han (більше ніж) -* `ge`: `g`reater than or `e`qual (більше або дорівнює) -* `lt`: `l`ess `t`han (менше ніж) -* `le`: `l`ess than or `e`qual (менше або дорівнює) +* `gt`: `g`reater `t`han +* `ge`: `g`reater than or `e`qual +* `lt`: `l`ess `t`han +* `le`: `l`ess than or `e`qual /// info | Інформація -`Query`, `Path` та інші класи, які Ви побачите пізніше, є підкласами спільного класу `Param`. +`Query`, `Path` та інші класи, які ви побачите пізніше, є підкласами спільного класу `Param`. -Всі вони мають однакові параметри для додаткових перевірок і метаданих, які Ви вже бачили. +Всі вони мають однакові параметри для додаткових перевірок і метаданих, які ви вже бачили. /// /// note | Технічні деталі -Коли Ви імпортуєте `Query`, `Path` та інші з `fastapi`, насправді це функції. +Коли ви імпортуєте `Query`, `Path` та інші з `fastapi`, насправді це функції. При виклику вони повертають екземпляри класів з такими ж іменами. -Тобто Ви імпортуєте `Query`, яка є функцією. А коли Ви її викликаєте, вона повертає екземпляр класу, який теж називається `Query`. +Тобто ви імпортуєте `Query`, яка є функцією. А коли ви її викликаєте, вона повертає екземпляр класу, який теж називається `Query`. -Ці функції створені таким чином (замість використання класів напряму), щоб Ваш редактор не відзначав їхні типи як помилки. +Ці функції створені таким чином (замість використання класів напряму), щоб ваш редактор не відзначав їхні типи як помилки. -Таким чином, Ви можете користуватися своїм звичайним редактором і інструментами для програмування без додаткових налаштувань для ігнорування таких помилок. +Таким чином, ви можете користуватися своїм звичайним редактором і інструментами для програмування без додаткових налаштувань для ігнорування таких помилок. /// diff --git a/docs/uk/docs/tutorial/path-params.md b/docs/uk/docs/tutorial/path-params.md index da4ff2f9ea..0598905495 100644 --- a/docs/uk/docs/tutorial/path-params.md +++ b/docs/uk/docs/tutorial/path-params.md @@ -1,34 +1,34 @@ -# Path Параметри +# Параметри шляху { #path-parameters } -Ви можете визначити "параметри" або "змінні" шляху, використовуючи синтаксис форматованих рядків: +Ви можете оголосити «параметри» або «змінні» шляху, використовуючи той самий синтаксис, що й у форматованих рядках Python: -{* ../../docs_src/path_params/tutorial001.py hl[6:7] *} +{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *} -Значення параметра шляху `item_id` передається у функцію як аргумент `item_id`. +Значення параметра шляху `item_id` буде передано у вашу функцію як аргумент `item_id`. -Якщо запустити цей приклад та перейти за посиланням http://127.0.0.1:8000/items/foo, то отримаємо таку відповідь: +Отже, якщо ви запустите цей приклад і перейдете за посиланням http://127.0.0.1:8000/items/foo, то побачите відповідь: ```JSON {"item_id":"foo"} ``` -## Path параметри з типами +## Параметри шляху з типами { #path-parameters-with-types } -Ви можете визначити тип параметра шляху у функції, використовуючи стандартні анотації типів Python: +Ви можете оголосити тип параметра шляху у функції, використовуючи стандартні анотації типів Python: -{* ../../docs_src/path_params/tutorial002.py hl[7] *} +{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *} -У такому випадку `item_id` визначається як `int`. +У цьому випадку `item_id` оголошено як `int`. /// check | Примітка -Це дасть можливість підтримки редактора всередині функції з перевірками помилок, автодоповнення тощо. +Це дасть вам підтримку редактора всередині функції з перевірками помилок, автодоповненням тощо. /// -## Перетворення даних +## Перетворення даних { #data-conversion } -Якщо запустити цей приклад і перейти за посиланням http://127.0.0.1:8000/items/3, то отримаєте таку відповідь: +Якщо ви запустите цей приклад і відкриєте у браузері http://127.0.0.1:8000/items/3, то побачите відповідь: ```JSON {"item_id":3} @@ -36,15 +36,15 @@ /// check | Примітка -Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`. Це Python `int`, а не рядок `"3"`. +Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`, як Python `int`, а не рядок `"3"`. -Отже, з таким оголошенням типу **FastAPI** автоматично виконує "парсинг" запитів. +Отже, з таким оголошенням типу **FastAPI** надає вам автоматичний «parsing» запиту. /// -## Перевірка даних +## Валідація даних { #data-validation } -Якщо ж відкрити у браузері посилання http://127.0.0.1:8000/items/foo, то побачимо цікаву HTTP-помилку: +Але якщо ви перейдете у браузері за посиланням http://127.0.0.1:8000/items/foo, ви побачите гарну HTTP-помилку: ```JSON { @@ -61,144 +61,136 @@ ] } ``` -тому що параметр шляху має значення `"foo"`, яке не є типом `int`. -Таку саму помилку отримаємо, якщо передати `float` замість `int`, як бачимо, у цьому прикладі: http://127.0.0.1:8000/items/4.2 +тому що параметр шляху `item_id` мав значення `"foo"`, яке не є `int`. + +Та сама помилка з’явиться, якщо ви передасте `float` замість `int`, як у: http://127.0.0.1:8000/items/4.2 /// check | Примітка -Отже, **FastAPI** надає перевірку типів з таким самим оголошенням типу в Python. +Отже, з тим самим оголошенням типу в Python **FastAPI** надає вам валідацію даних. -Зверніть увагу, що помилка також чітко вказує саме на те місце, де валідація не пройшла. +Зверніть увагу, що помилка також чітко вказує саме місце, де валідація не пройшла. -Це неймовірно корисно під час розробки та дебагінгу коду, що взаємодіє з вашим API. +Це неймовірно корисно під час розробки та налагодження коду, що взаємодіє з вашим API. /// -## Документація +## Документація { #documentation } -Тепер коли відкриєте свій браузер за посиланням http://127.0.0.1:8000/docs, то побачите автоматично згенеровану, інтерактивну API-документацію: +А коли ви відкриєте у браузері http://127.0.0.1:8000/docs, ви побачите автоматичну, інтерактивну, API-документацію на кшталт: /// check | Примітка -Знову ж таки, лише з цим самим оголошенням типу в Python, FastAPI надає вам автоматичну, інтерактивну документацію (з інтеграцією Swagger UI). - -Зверніть увагу, що параметр шляху оголошений як ціле число. +Знову ж таки, лише з тим самим оголошенням типу в Python **FastAPI** надає вам автоматичну, інтерактивну документацію (з інтеграцією Swagger UI). +Зверніть увагу, що параметр шляху оголошено як ціле число. /// -## Переваги стандартизації, альтернативна документація +## Переваги стандартів, альтернативна документація { #standards-based-benefits-alternative-documentation } І оскільки згенерована схема відповідає стандарту OpenAPI, існує багато сумісних інструментів. -З цієї причини FastAPI також надає альтернативну документацію API (використовуючи ReDoc), до якої можна отримати доступ за посиланням http://127.0.0.1:8000/redoc: +Через це **FastAPI** також надає альтернативну API-документацію (використовуючи ReDoc), до якої ви можете отримати доступ за посиланням http://127.0.0.1:8000/redoc: -Таким чином, існує багато сумісних інструментів, включаючи інструменти для генерації коду для багатьох мов. +Так само, існує багато сумісних інструментів. Зокрема інструменти генерації коду для багатьох мов. +## Pydantic { #pydantic } -## Pydantic +Уся валідація даних виконується за лаштунками за допомогою Pydantic, тож ви отримуєте всі переваги від його використання. І ви знаєте, що ви в надійних руках. -Вся валідація даних виконується за лаштунками за допомогою Pydantic, тому Ви отримуєте всі переваги від його використання. І можете бути впевнені, що все в надійних руках. +Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних. -Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних. +Декілька з них розглядаються в наступних розділах посібника. -Декілька з них будуть розглянуті в наступних розділах посібника. +## Порядок має значення { #order-matters } -## Порядок має значення +Під час створення *операцій шляху* можуть виникати ситуації, коли у вас є фіксований шлях. -При створенні *операцій шляху* можуть виникати ситуації, коли шлях фіксований. +Наприклад, `/users/me` — припустімо, це для отримання даних про поточного користувача. -Наприклад, `/users/me`. Припустимо, що це шлях для отримання даних про поточного користувача. +І тоді у вас також може бути шлях `/users/{user_id}` для отримання даних про конкретного користувача за його ID. -А також у вас може бути шлях `/users/{user_id}`, щоб отримати дані про конкретного користувача за його ID. +Оскільки *операції шляху* оцінюються по черзі, вам потрібно переконатися, що шлях для `/users/me` оголошено перед шляхом для `/users/{user_id}`: -Оскільки *операції шляху* оцінюються по черзі, Ви повинні переконатися, що шлях для `/users/me` оголошений перед шляхом для `/users/{user_id}`: +{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *} -{* ../../docs_src/path_params/tutorial003.py hl[6,11] *} +Інакше шлях для `/users/{user_id}` також відповідатиме `/users/me`, «вважаючи», що отримує параметр `user_id` зі значенням `"me"`. -Інакше шлях для `/users/{user_id}` також буде відповідати для `/users/me`, "вважаючи", що він отримує параметр `user_id` зі значенням `"me"`. +Так само ви не можете перевизначити операцію шляху: -Аналогічно, Ви не можете оголосити операцію шляху: +{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *} -{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *} +Завжди використовуватиметься перша, оскільки шлях збігається першим. -Перша операція буде завжди використовуватися, оскільки шлях збігається першим. -## Попередньо визначені значення +## Попередньо визначені значення { #predefined-values } -Якщо у вас є *операція шляху*, яка приймає *параметр шляху*, але Ви хочете, щоб можливі допустимі значення *параметра шляху* були попередньо визначені, Ви можете використати стандартний Python Enum. +Якщо у вас є *операція шляху*, яка отримує *параметр шляху*, але ви хочете, щоб можливі коректні значення *параметра шляху* були попередньо визначені, ви можете використати стандартний Python `Enum`. -### Створення класу `Enum` +### Створіть клас `Enum` { #create-an-enum-class } Імпортуйте `Enum` і створіть підклас, що наслідується від `str` та `Enum`. -Наслідуючи від `str`, документація API зможе визначити, що значення повинні бути типу `string`, і правильно їх відобразить. - -Після цього створіть атрибути класу з фіксованими значеннями, які будуть доступними допустимими значеннями: +Завдяки наслідуванню від `str` документація API зможе визначити, що значення повинні бути типу `string`, і зможе коректно їх відобразити. -{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *} +Після цього створіть атрибути класу з фіксованими значеннями, які будуть доступними коректними значеннями: -/// info | Додаткова інформація - -Перелічення (або enums) доступні в Python починаючи з версії 3.4. - -/// +{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *} /// tip | Порада -Якщо вам цікаво, "AlexNet", "ResNet" та "LeNet" — це просто назви ML моделей Machine Learning. +Якщо вам цікаво, «AlexNet», «ResNet» та «LeNet» — це просто назви Machine Learning models. /// - -### Оголосіть *параметр шляху* +### Оголосіть *параметр шляху* { #declare-a-path-parameter } Потім створіть *параметр шляху* з анотацією типу, використовуючи створений вами клас enum (`ModelName`): -{* ../../docs_src/path_params/tutorial005.py hl[16] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *} -### Перевірка документації +### Перевірте документацію { #check-the-docs } -Оскільки доступні значення для *параметра шляху* визначені заздалегідь, інтерактивна документація зможе красиво їх відобразити: +Оскільки доступні значення для *параметра шляху* визначені заздалегідь, інтерактивна документація може красиво їх показати: -### Робота з *перелічуваннями* у Python +### Робота з Python *переліченнями* { #working-with-python-enumerations } -Значення *параметра шляху* буде елементом *перелічування*. +Значення *параметра шляху* буде *елементом перелічування*. -#### Порівняння *елементів перелічування* +#### Порівняйте *елементи перелічування* { #compare-enumeration-members } -Ви можете порівнювати його з *елементами перелічування* у створеному вами enum `ModelName`: +Ви можете порівнювати його з *елементом перелічування* у створеному вами enum `ModelName`: -{* ../../docs_src/path_params/tutorial005.py hl[17] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *} -#### Отримання *значення перелічування* +#### Отримайте *значення перелічування* { #get-the-enumeration-value } Ви можете отримати фактичне значення (у цьому випадку це `str`), використовуючи `model_name.value`, або загалом `your_enum_member.value`: -{* ../../docs_src/path_params/tutorial005.py hl[20] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *} /// tip | Порада -Ви також можете отримати доступ до значення `"lenet"`, використовуючи `ModelName.lenet.value`. +Ви також можете отримати доступ до значення `"lenet"` через `ModelName.lenet.value`. /// +#### Поверніть *елементи перелічування* { #return-enumeration-members } -#### Повернення *елементів перелічування* - -Ви можете повертати *елементи перелічування* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`). +Ви можете повертати *елементи enum* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`). Вони будуть перетворені на відповідні значення (у цьому випадку рядки) перед поверненням клієнту: -{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *} +{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *} -На стороні клієнта Ви отримаєте відповідь у форматі JSON, наприклад: +На стороні клієнта ви отримаєте відповідь у форматі JSON, наприклад: ```JSON { @@ -207,36 +199,35 @@ } ``` -## Path-параметри, що містять шляхи - -Припустимо, у вас є *операція шляху* з маршрутом `/files/{file_path}`. +## Параметри шляху, що містять шляхи { #path-parameters-containing-paths } -Але вам потрібно, щоб `file_path` містив *шлях*, наприклад `home/johndoe/myfile.txt`. +Припустімо, у вас є *операція шляху* зі шляхом `/files/{file_path}`. -Отже, URL для цього файлу виглядатиме так: `/files/home/johndoe/myfile.txt`. +Але вам потрібно, щоб `file_path` сам містив *шлях*, наприклад `home/johndoe/myfile.txt`. +Отже, URL для цього файлу виглядатиме приблизно так: `/files/home/johndoe/myfile.txt`. +### Підтримка OpenAPI { #openapi-support } -### Підтримка OpenAPI +OpenAPI не підтримує спосіб оголошення *параметра шляху*, який має містити всередині *шлях*, оскільки це може призвести до сценаріїв, які складно тестувати та визначати. -OpenAPI не підтримує спосіб оголошення *параметра шляху*, що містить *шлях* всередині, оскільки це може призвести до сценаріїв, які складно тестувати та визначати. +Проте ви все одно можете зробити це в **FastAPI**, використовуючи один із внутрішніх інструментів Starlette. -Однак (одначе), Ви все одно можете зробити це в **FastAPI**, використовуючи один із внутрішніх інструментів Starlette. +І документація все ще працюватиме, хоча й не додаватиме жодної документації, яка б казала, що параметр має містити шлях. -Документація все ще працюватиме, хоча й не додаватиме опису про те, що параметр повинен містити шлях. +### Конвертер шляху { #path-convertor } -### Конвертер шляху - -Використовуючи опцію безпосередньо зі Starlette, Ви можете оголосити *параметр шляху*, що містить *шлях*, використовуючи URL на кшталт: +Використовуючи опцію безпосередньо зі Starlette, ви можете оголосити *параметр шляху*, що містить *шлях*, використовуючи URL на кшталт: ``` /files/{file_path:path} ``` -У цьому випадку ім'я параметра — `file_path`, а остання частина `:path` вказує на те, що параметр повинен відповідати будь-якому *шляху*. -Отже, Ви можете використати його так: +У цьому випадку ім’я параметра — `file_path`, а остання частина `:path` вказує, що параметр має відповідати будь-якому *шляху*. + +Отже, ви можете використати його так: -{* ../../docs_src/path_params/tutorial004.py hl[6] *} +{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *} /// tip | Порада @@ -246,15 +237,15 @@ OpenAPI не підтримує спосіб оголошення *параме /// -## Підсумок +## Підсумок { #recap } -З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, Ви отримуєте: +З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, ви отримуєте: -* Підтримку в редакторі: перевірка помилок, автодоповнення тощо. -* "Парсинг" даних +* Підтримку редактора: перевірка помилок, автодоповнення тощо. +* Перетворення даних «parsing» * Валідацію даних * Анотацію API та автоматичну документацію І вам потрібно оголосити їх лише один раз. -Це, ймовірно, основна видима перевага **FastAPI** порівняно з альтернативними фреймворками (окрім високої продуктивності). +Це, ймовірно, основна видима перевага **FastAPI** порівняно з альтернативними фреймворками (окрім сирої продуктивності). diff --git a/docs/uk/docs/tutorial/query-param-models.md b/docs/uk/docs/tutorial/query-param-models.md index 97eb82fa1b..a28bf6c27c 100644 --- a/docs/uk/docs/tutorial/query-param-models.md +++ b/docs/uk/docs/tutorial/query-param-models.md @@ -1,4 +1,4 @@ -# Моделі Query параметрів +# Моделі параметрів запиту { #query-parameter-models } Якщо у Вас є група **query параметрів**, які пов’язані між собою, Ви можете створити **Pydantic-модель** для їх оголошення. @@ -10,7 +10,7 @@ /// -## Query параметри з Pydantic-моделлю +## Query параметри з Pydantic-моделлю { #query-parameters-with-a-pydantic-model } Оголосіть **query параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть цей параметр як `Query`: @@ -18,7 +18,7 @@ **FastAPI** буде **витягувати** дані для **кожного поля** з **query параметрів** у запиті та передавати їх у визначену вами Pydantic-модель. -## Перевірте документацію +## Перевірте документацію { #check-the-docs } Ви можете побачити параметри запиту в UI документації за `/docs`: @@ -26,7 +26,7 @@ -## Заборона зайвих Query параметрів +## Заборона зайвих Query параметрів { #forbid-extra-query-parameters } У деяких особливих випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** query параметри, які дозволено отримувати. @@ -34,7 +34,7 @@ {* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *} -Якщо клієнт спробує надіслати **зайві** дані у **query параметрах**, він отримає **помилку**. +Якщо клієнт спробує надіслати **зайві** дані у **query параметрах**, він отримає **помилку** відповідь. Наприклад, якщо клієнт спробує надіслати query параметр `tool` зі значенням `plumbus`, як у цьому запиті: @@ -57,11 +57,11 @@ https://example.com/items/?limit=10&tool=plumbus } ``` -## Підсумок +## Підсумок { #summary } Ви можете використовувати **Pydantic-моделі** для оголошення **query параметрів** у **FastAPI**. 😎 -/// tip | Підказка +/// tip | Порада Спойлер: Ви також можете використовувати Pydantic-моделі для оголошення cookie та заголовків, але про це Ви дізнаєтеся пізніше в цьому посібнику. 🤫 diff --git a/docs/uk/docs/tutorial/query-params-str-validations.md b/docs/uk/docs/tutorial/query-params-str-validations.md index cd3f4ad935..414987880b 100644 --- a/docs/uk/docs/tutorial/query-params-str-validations.md +++ b/docs/uk/docs/tutorial/query-params-str-validations.md @@ -1,26 +1,26 @@ -# Query параметри та валідація рядків +# Query параметри та валідація рядків { #query-parameters-and-string-validations } -**FastAPI** дозволяє оголошувати додаткову інформацію та виконувати валідацію для Ваших параметрів. +**FastAPI** дозволяє оголошувати додаткову інформацію та виконувати валідацію для ваших параметрів. Розглянемо цей додаток як приклад: {* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *} -Query параметр `q` має тип `str | None`, що означає, що він може бути як `str`, так і `None`. За замовчуванням він має значення `None`, тому FastAPI розуміє, що цей параметр не є обов'язковим. +Query параметр `q` має тип `str | None`, що означає, що він має тип `str`, але також може бути `None`, і справді, значення за замовчуванням — `None`, тож FastAPI знатиме, що він не є обов'язковим. /// note | Примітка -FastAPI знає, що `q` не є обов’язковим, завдяки значенню за замовчуванням `= None`. +FastAPI знатиме, що значення `q` не є обов’язковим, завдяки значенню за замовчуванням `= None`. -Використання `str | None` дозволить Вашому редактору коду надавати кращу підтримку та виявляти помилки. +Використання `str | None` дозволить вашому редактору коду надавати кращу підтримку та виявляти помилки. /// -## Додаткова валідація +## Додаткова валідація { #additional-validation } -Ми хочемо, щоб навіть якщо `q` є необов’язковим, **його довжина не перевищувала 50 символів**, якщо він все ж буде переданий. +Ми хочемо, щоб навіть якщо `q` є необов’язковим, коли його передають, **його довжина не перевищувала 50 символів**. -### Імпорт `Query` та `Annotated` +### Імпорт `Query` та `Annotated` { #import-query-and-annotated } Щоб це зробити, спочатку імпортуємо: @@ -33,13 +33,13 @@ FastAPI знає, що `q` не є обов’язковим, завдяки з FastAPI додав підтримку `Annotated` (і почав рекомендувати його) у версії 0.95.0. -Якщо у Вас старіша версія, під час використання `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){.internal-link target=_blank} до принаймні 0.95.1, перш ніж використовувати `Annotated`. /// -## Використання `Annotated` у типі параметра `q` +## Використання `Annotated` у типі параметра `q` { #use-annotated-in-the-type-for-the-q-parameter } Пам’ятаєте, як я раніше розповідав, що `Annotated` можна використовувати для додавання метаданих до параметрів у [Вступі до типів Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}? @@ -55,7 +55,7 @@ q: str | None = None //// -//// tab | Python 3.8+ +//// tab | Python 3.9+ ```Python q: Union[str, None] = None @@ -73,7 +73,7 @@ q: Annotated[str | None] = None //// -//// tab | Python 3.8+ +//// tab | Python 3.9+ ```Python q: Annotated[Union[str, None]] = None @@ -85,33 +85,33 @@ q: Annotated[Union[str, None]] = None А тепер переходимо до цікавого! 🎉 -## Додавання `Query` до `Annotated` у параметр `q` +## Додавання `Query` до `Annotated` у параметр `q` { #add-query-to-annotated-in-the-q-parameter } -Тепер, коли у нас є `Annotated`, де ми можемо додавати додаткову інформацію (зокрема валідацію), додамо `Query` всередину `Annotated` і встановимо параметр `max_length` у `50`: +Тепер, коли у нас є `Annotated`, де ми можемо додавати додаткову інформацію (у цьому випадку — додаткову валідацію), додамо `Query` всередину `Annotated` і встановимо параметр `max_length` у `50`: {* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *} Зверніть увагу, що значення за замовчуванням усе ще `None`, тому параметр залишається необов'язковим. -Але тепер, додавши `Query(max_length=50)` всередину `Annotated`, ми повідомляємо FastAPI, що хочемо **додаткову валідацію** для цього значення — воно має містити максимум 50 символів. 😎 +Але тепер, додавши `Query(max_length=50)` всередину `Annotated`, ми повідомляємо FastAPI, що хочемо **додаткову валідацію** для цього значення: ми хочемо, щоб воно мало максимум 50 символів. 😎 -/// tip | Підказка +/// tip | Порада -Ми використовуємо `Query()`, оскільки це **query параметр**. Далі ми розглянемо інші варіанти, як-от `Path()`, `Body()`, `Header()` та `Cookie()`, які приймають ті самі аргументи, що й `Query()`. +Тут ми використовуємо `Query()`, оскільки це **query параметр**. Далі ми розглянемо інші варіанти, як-от `Path()`, `Body()`, `Header()` та `Cookie()`, які приймають ті самі аргументи, що й `Query()`. /// Тепер FastAPI: -* **Перевірить** дані, щоб переконатися, що їхня довжина не перевищує 50 символів +* **Перевірить** дані, щоб переконатися, що їхня максимальна довжина — 50 символів * Покажe **чітку помилку** клієнту, якщо дані недійсні * **Задокументує** параметр в OpenAPI-схемі *операції шляху* (що відобразиться в **автоматично згенерованій документації**) -## Альтернативний (застарілий) метод: Query як значення за замовчуванням +## Альтернативний (застарілий) метод: `Query` як значення за замовчуванням { #alternative-old-query-as-the-default-value } -У попередніх версіях FastAPI (до 0.95.0) `Query` використовувався як значення за замовчуванням для параметра, а не всередині `Annotated`. Ви, ймовірно, побачите код, який використовує цей підхід, тому варто розглянути його. +У попередніх версіях FastAPI (до 0.95.0) потрібно було використовувати `Query` як значення за замовчуванням параметра, замість того, щоб додавати його в `Annotated`. Є висока ймовірність, що ви зустрінете код із таким підходом, тож я поясню його. -/// tip | Підказка +/// tip | Порада Для нового коду та коли це можливо, використовуйте `Annotated`, як показано вище. Це має багато переваг (пояснених нижче) і не має недоліків. 🍰 @@ -121,7 +121,7 @@ q: Annotated[Union[str, None]] = None {* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *} -Оскільки в цьому випадку (без `Annotated`) нам потрібно замінити `None` у функції на `Query()`, тепер ми повинні явно встановити значення за замовчуванням через параметр `Query(default=None)`. Це виконує ту саму роль визначення значення за замовчуванням (принаймні для FastAPI). +Оскільки в цьому випадку (без `Annotated`) нам потрібно замінити значення за замовчуванням `None` у функції на `Query()`, тепер ми повинні встановити значення за замовчуванням через параметр `Query(default=None)`. Це виконує ту саму роль визначення значення за замовчуванням (принаймні для FastAPI). Таким чином: @@ -135,9 +135,10 @@ q: str | None = Query(default=None) ```Python q: str | None = None ``` -Але у версії з `Query` ми явно вказуємо, що це query параметр. -Далі ми можемо передавати `Query` додаткові параметри, зокрема `max_length`, який застосовується до рядків: +Але у версії з `Query` ми явно вказуємо, що це query параметр. + +Далі ми можемо передавати `Query` додаткові параметри. У цьому випадку — параметр `max_length`, який застосовується до рядків: ```Python q: str | None = Query(default=None, max_length=50) @@ -145,11 +146,11 @@ q: str | None = Query(default=None, max_length=50) Це забезпечить валідацію даних, виведе зрозумілу помилку у разі недійсних даних і задокументує параметр у схемі OpenAPI *операції шляху*. -### `Query` як значення за замовчуванням або всередині `Annotated` +### `Query` як значення за замовчуванням або всередині `Annotated` { #query-as-the-default-value-or-in-annotated } Важливо пам’ятати, якщо використовувати `Query` всередині `Annotated`, не можна задавати параметр `default` у `Query`. -Замість цього використовуйте значення за замовчуванням у самій функції. Інакше це буде нелогічно. +Замість цього використовуйте фактичне значення за замовчуванням параметра функції. Інакше це буде непослідовно. Наприклад, цей варіант є некоректним: @@ -159,39 +160,39 @@ q: Annotated[str, Query(default="rick")] = "morty" ...тому, що не зрозуміло, яке значення має бути значенням за замовчуванням: `"rick"` чи `"morty"`. -Коректні варіанти: +Тож ви будете використовувати (бажано): ```Python q: Annotated[str, Query()] = "rick" ``` -...або у старих кодових базах Ви знайдете: +...або у старих кодових базах ви знайдете: ```Python q: str = Query(default="rick") ``` -### Переваги використання `Annotated` +### Переваги використання `Annotated` { #advantages-of-annotated } **Використання `Annotated` є рекомендованим** замість задання значення за замовчуванням у параметрах функції, оскільки воно **краще** з кількох причин. 🤓 -Значення **за замовчуванням** параметра **функції** є його **фактичним значенням за замовчуванням**, що є більш інтуїтивним у Python загалом. 😌 +Значення **за замовчуванням** параметра **функції** є **фактичним значенням за замовчуванням**, що є більш інтуїтивним у Python загалом. 😌 -Ви можете **викликати** ту саму функцію **в інших місцях** без FastAPI, і вона **працюватиме очікувано**. Якщо параметр є **обов’язковим** (без значення за замовчуванням), Ваш **редактор** повідомить про помилку, а **Python** також видасть помилку, якщо Ви виконаєте функцію без передавання цього параметра. +Ви можете **викликати** ту саму функцію **в інших місцях** без FastAPI, і вона **працюватиме очікувано**. Якщо параметр є **обов’язковим** (без значення за замовчуванням), ваш **редактор** повідомить про помилку, а **Python** також видасть помилку, якщо ви виконаєте функцію без передавання цього параметра. -Якщо Ви не використовуєте `Annotated`, а використовуєте **(старий) стиль значень за замовчуванням**, то при виклику цієї функції без FastAPI **в інших місцях**, потрібно **не забути** передати їй аргументи, інакше значення будуть відрізнятися від очікуваних (наприклад, Ви отримаєте `QueryInfo` або подібне замість `str`). Ваш редактор не повідомить про помилку, і Python також не видасть помилку при запуску функції, поки не виникне помилка під час виконання операцій усередині. +Якщо ви не використовуєте `Annotated`, а використовуєте **(старий) стиль значень за замовчуванням**, то при виклику цієї функції без FastAPI **в інших місцях**, потрібно **пам’ятати** передати їй аргументи, щоб вона працювала коректно, інакше значення будуть відрізнятися від очікуваних (наприклад, ви отримаєте `QueryInfo` або щось подібне замість `str`). І ваш редактор не повідомить про помилку, і Python не скаржитиметься під час запуску цієї функції — лише коли операції всередині завершаться помилкою. -Оскільки `Annotated` може містити кілька анотацій метаданих, Ви навіть можете використовувати ту саму функцію з іншими інструментами, такими як Typer. 🚀 +Оскільки `Annotated` може містити кілька анотацій метаданих, тепер ви навіть можете використовувати ту саму функцію з іншими інструментами, такими як Typer. 🚀 -## Додавання додаткових валідацій +## Додавання додаткових валідацій { #add-more-validations } Ви також можете додати параметр `min_length`: {* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *} -## Додавання регулярних виразів +## Додавання регулярних виразів { #add-regular-expressions } -Ви можете визначити регулярний вираз pattern, якому має відповідати параметр: +Ви можете визначити regular expression `pattern`, якому має відповідати параметр: {* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *} @@ -201,41 +202,27 @@ q: str = Query(default="rick") * `fixedquery`: точно відповідає значенню `fixedquery`. * `$`: закінчується тут, після `fixedquery` немає жодних символів. -Якщо Ви почуваєтеся розгублено щодо **"регулярних виразів"**, не хвилюйтеся. Вони є складною темою для багатьох людей. Ви все одно можете зробити багато речей без їх використання. - -Але тепер Ви знаєте, що коли вони знадобляться, їх можна застосовувати у **FastAPI**. - -### Pydantic v1 `regex` замість `pattern` - -До версії Pydantic 2 і FastAPI 0.100.0 параметр називався `regex` замість `pattern`, але тепер він застарів. +Якщо ви почуваєтеся розгублено щодо **«regular expression»**, не хвилюйтеся. Це складна тема для багатьох людей. Ви все одно можете робити багато речей без використання регулярних виразів. -Ви все ще можете зустріти код, який використовує його: - -//// tab | Pydantic v1 - -{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *} - -//// +Тепер ви знаєте, що коли вони знадобляться, їх можна застосовувати у **FastAPI**. -Але майте на увазі, що він є застарілим і його слід оновити до нового параметра `pattern`. 🤓 +## Значення за замовчуванням { #default-values } -## Значення за замовчуванням +Ви можете, звісно, використовувати значення за замовчуванням, відмінні від `None`. -Ви можете використовувати значення за замовчуванням, відмінні від `None`. - -Наприклад, якщо Ви хочете оголосити параметр запиту `q` з `min_length` `3` і значенням за замовчуванням `"fixedquery"`: +Припустімо, що ви хочете оголосити query параметр `q` з `min_length` `3` і значенням за замовчуванням `"fixedquery"`: {* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *} -/// note | Технічні деталі +/// note | Примітка Наявність значення за замовчуванням будь-якого типу, включаючи `None`, робить параметр необов’язковим (not required). /// -## Обов’язкові параметри +## Обов’язкові параметри { #required-parameters } -Якщо нам не потрібно вказувати додаткові перевірки або метадані, ми можемо зробити параметр `q` обов’язковим, просто не оголошуючи значення за замовчуванням, наприклад: +Якщо нам не потрібно оголошувати додаткові валідації або метадані, ми можемо зробити query параметр `q` обов’язковим, просто не вказуючи значення за замовчуванням, наприклад: ```Python q: str @@ -247,43 +234,39 @@ q: str q: str | None = None ``` -Але тепер ми оголошуємо його з `Query`, наприклад: - -//// tab | Annotated +Але тепер ми оголошуємо його з `Query`, наприклад так: ```Python q: Annotated[str | None, Query(min_length=3)] = None ``` -//// - -Тому, якщо Вам потрібно зробити значення обов’язковим, використовуючи `Query`, просто не вказуйте значення за замовчуванням: +Тому, якщо вам потрібно оголосити значення як обов’язкове під час використання `Query`, просто не вказуйте значення за замовчуванням: {* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *} -### Обов’язкове значення, яке може бути `None` +### Обов’язковий, може бути `None` { #required-can-be-none } -Ви можете вказати, що параметр може приймати `None`, але при цьому залишається обов’язковим. Це змусить клієнтів надіслати значення, навіть якщо воно дорівнює `None`. +Ви можете вказати, що параметр може приймати `None`, але при цьому залишається обов’язковим. Це змусить клієнтів надіслати значення, навіть якщо значення дорівнює `None`. -Щоб зробити це, оголосіть, що `None` є допустимим типом, але не вказуйте значення за замовчуванням: +Щоб зробити це, оголосіть, що `None` є допустимим типом, але просто не вказуйте значення за замовчуванням: {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} -## Список параметрів запиту / кілька значень +## Список query параметрів / кілька значень { #query-parameter-list-multiple-values } -Якщо Ви визначаєте параметр запиту за допомогою `Query`, Ви також можете дозволити отримання списку значень, тобто дозволити отримання кількох значень. +Коли ви явно визначаєте query параметр за допомогою `Query`, ви також можете оголосити, що він має приймати список значень, або, іншими словами, кілька значень. -Наприклад, щоб дозволити параметру запиту `q` з'являтися кілька разів в URL, можна написати: +Наприклад, щоб оголосити query параметр `q`, який може з’являтися в URL кілька разів, можна написати: {* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *} -Тоді, у випадку запиту за URL: +Тоді, у випадку URL: ``` http://localhost:8000/items/?q=foo&q=bar ``` -Ви отримаєте кілька значень *query параметра* `q` (`foo` і `bar`) у вигляді списку `list` в Python у Вашій *функції обробки шляху*, у *параметрі функції* `q`. +ви отримаєте кілька значень `q` *query параметрів* (`foo` і `bar`) у вигляді Python `list` у вашій *функції операції шляху*, у *параметрі функції* `q`. Отже, відповідь на цей URL буде: @@ -296,9 +279,9 @@ http://localhost:8000/items/?q=foo&q=bar } ``` -/// tip | Підказка +/// tip | Порада -Щоб оголосити параметр запиту з типом `list`, як у наведеному вище прикладі, потрібно явно використовувати `Query`, інакше він буде інтерпретований як тіло запиту. +Щоб оголосити query параметр з типом `list`, як у наведеному вище прикладі, потрібно явно використовувати `Query`, інакше він буде інтерпретований як тіло запиту. /// @@ -306,19 +289,19 @@ http://localhost:8000/items/?q=foo&q=bar -### Список параметрів запиту / кілька значень за замовчуванням +### Список query параметрів / кілька значень за замовчуванням { #query-parameter-list-multiple-values-with-defaults } -Ви також можете визначити значення за замовчуванням для `list`, якщо жодне значення не було передане: +Ви також можете визначити значення за замовчуванням `list`, якщо жодне значення не було передане: {* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *} -Якщо Ви перейдете за посиланням: +Якщо ви перейдете за посиланням: ``` http://localhost:8000/items/ ``` -то значення `q` за замовчуванням буде: `["foo", "bar"]`, і Ваша відповідь виглядатиме так: +то значення `q` за замовчуванням буде: `["foo", "bar"]`, і ваша відповідь виглядатиме так: ```JSON { @@ -329,35 +312,35 @@ http://localhost:8000/items/ } ``` -#### Використання тільки `list` +#### Використання тільки `list` { #using-just-list } -Ви також можете використовувати `list` без уточнення типу, замість `list[str]`: +Ви також можете використовувати `list` напряму замість `list[str]`: {* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *} -/// note | Технічні деталі +/// note | Примітка Майте на увазі, що в цьому випадку FastAPI не перевірятиме вміст списку. -Наприклад, `list[int]` перевірятиме (і документуватиме), що всі елементи списку є цілими числами. Але `list` без уточнення цього не робитиме. +Наприклад, `list[int]` перевірятиме (і документуватиме), що вміст списку — цілі числа. Але `list` без уточнення цього не робитиме. /// -## Додавання додаткових метаданих +## Оголосити більше метаданих { #declare-more-metadata } Ви можете додати більше інформації про параметр. -Ця інформація буде включена у згенерований OpenAPI та використана в інтерфейсах документації та зовнішніх інструментах. +Ця інформація буде включена у згенерований OpenAPI та використана інтерфейсами документації та зовнішніми інструментами. -/// note | Технічні деталі +/// note | Примітка Майте на увазі, що різні інструменти можуть мати різний рівень підтримки OpenAPI. -Деякі з них можуть ще не відображати всю додаткову інформацію, хоча в більшості випадків ця функція вже запланована для розробки. +Деякі з них можуть ще не відображати всю додаткову інформацію, хоча в більшості випадків відсутню функцію вже заплановано до реалізації. /// -Ви можете додати `title` : +Ви можете додати `title`: {* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *} @@ -365,9 +348,9 @@ http://localhost:8000/items/ {* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *} -## Аліаси параметрів +## Аліаси параметрів { #alias-parameters } -Уявіть, що Ви хочете, щоб параметр називався `item-query`. +Уявіть, що ви хочете, щоб параметр називався `item-query`. Наприклад: @@ -379,19 +362,19 @@ http://127.0.0.1:8000/items/?item-query=foobaritems Найближчий допустимий варіант — `item_query`. -Проте Вам потрібно, щоб параметр залишався саме `item-query`... +Проте вам потрібно, щоб параметр залишався саме `item-query`... У такому випадку можна оголосити `alias`, і саме він буде використовуватися для отримання значення параметра: {* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *} -## Виведення параметрів як застарілих +## Позначення параметрів як застарілих { #deprecating-parameters } -Припустимо, що Ви більше не хочете використовувати цей параметр. +Припустімо, що вам більше не подобається цей параметр. -Вам потрібно залишити його на деякий час, оскільки ним користуються клієнти, але Ви хочете, щоб документація чітко показувала, що він є застарілим. +Вам потрібно залишити його на деякий час, оскільки ним користуються клієнти, але ви хочете, щоб документація чітко показувала, що він є deprecated. -Тоді Ви можете передати параметр `deprecated=True` до `Query`: +Тоді передайте параметр `deprecated=True` до `Query`: {* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *} @@ -399,27 +382,27 @@ http://127.0.0.1:8000/items/?item-query=foobaritems -## Виняток параметрів з OpenAPI +## Виняток параметрів з OpenAPI { #exclude-parameters-from-openapi } -Щоб виключити параметр запиту зі згенерованої схеми OpenAPI (і, таким чином, з автоматичних систем документації), встановіть параметр `include_in_schema` для `Query` в `False`: +Щоб виключити query параметр зі згенерованої схеми OpenAPI (і, таким чином, з автоматичних систем документації), встановіть параметр `include_in_schema` для `Query` в `False`: {* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *} -## Кастомна валідація +## Кастомна валідація { #custom-validation } -Можуть бути випадки, коли Вам потрібно провести **кастомну валідацію**, яку не можна реалізувати за допомогою параметрів, показаних вище. +Можуть бути випадки, коли вам потрібно провести **кастомну валідацію**, яку не можна реалізувати за допомогою параметрів, показаних вище. -У таких випадках ви можете використати **кастомну функцію валідації**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`). +У таких випадках ви можете використати **кастомну функцію-валідатор**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`). Це можна досягти за допомогою Pydantic's `AfterValidator` в середині `Annotated`. -/// tip | Підказка +/// tip | Порада Pydantic також має `BeforeValidator` та інші. 🤓 /// -Наприклад, цей кастомний валідатор перевіряє, чи починається ID елемента з `isbn-` для номера книги ISBN або з `imdb-` для ID URL фільму на IMDB: +Наприклад, цей кастомний валідатор перевіряє, чи починається ID елемента з `isbn-` для номера книги ISBN або з `imdb-` для ID URL фільму на IMDB: {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *} @@ -429,49 +412,49 @@ Pydantic також має ітерабельний об'єкт із кортежами, що містять ключ і значення для кожного елемента словника. +За допомогою `data.items()` ми отримуємо iterable object із кортежами, що містять ключ і значення для кожного елемента словника. -Ми перетворюємо цей ітерабельний об'єкт у звичайний `list` за допомогою `list(data.items())`. +Ми перетворюємо цей iterable object у звичайний `list` за допомогою `list(data.items())`. -Потім, використовуючи `random.choice()`, ми можемо отримати випадкове значення зі списку, тобто отримуємо кортеж із `(id, name)`. Це може бути щось на зразок `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`. +Потім, використовуючи `random.choice()`, ми можемо отримати **випадкове значення** зі списку, тобто отримуємо кортеж із `(id, name)`. Це може бути щось на зразок `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`. Далі ми **присвоюємо ці два значення** кортежу змінним `id` і `name`. Тож, якщо користувач не вказав ID елемента, він все одно отримає випадкову рекомендацію. -...і все це реалізовано в **одному рядку коду**. 🤯 Хіба не прекрасний Python? 🐍 +...ми робимо все це в **одному простому рядку**. 🤯 Хіба ви не любите Python? 🐍 {* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *} -## Підсумок +## Підсумок { #recap } -Ви можете оголошувати додаткові валідації та метаінформацію для своїх параметрів. +Ви можете оголошувати додаткові валідації та метадані для ваших параметрів. -Загальні валідації та метаінформація: +Загальні валідації та метадані: * `alias` * `title` @@ -486,6 +469,6 @@ Pydantic також має "Парсинг" даних +* Підтримка в редакторі (очевидно) +* «parsing» даних * Валідація даних * Автоматична документація +## Значення за замовчуванням { #defaults } -## Значення за замовчуванням - -Оскільки query параметри не є фіксованою частиною шляху, вони можуть бути необов’язковими та мати значення за замовчуванням. +Оскільки параметри query не є фіксованою частиною шляху, вони можуть бути необов’язковими та мати значення за замовчуванням. У наведеному вище прикладі вони мають значення за замовчуванням: `skip=0` і `limit=10`. -Отже, результат переходу за URL: +Отже, перехід за URL: ``` http://127.0.0.1:8000/items/ ``` + буде таким самим, як і перехід за посиланням: ``` http://127.0.0.1:8000/items/?skip=0&limit=10 ``` -Але якщо Ви перейдете, наприклад, за посиланням: +Але якщо ви перейдете, наприклад, за посиланням: ``` http://127.0.0.1:8000/items/?skip=20 @@ -54,12 +54,12 @@ http://127.0.0.1:8000/items/?skip=20 Значення параметрів у вашій функції будуть такими: -* `skip=20`: оскільки Ви вказали його в URL +* `skip=20`: оскільки ви вказали його в URL * `limit=10`: оскільки це значення за замовчуванням -## Необов'язкові параметри +## Необов'язкові параметри { #optional-parameters } -Аналогічно, Ви можете оголосити необов’язкові query параметри, встановивши для них значення за замовчуванням `None`: +Так само ви можете оголосити необов’язкові параметри query, встановивши для них значення за замовчуванням `None`: {* ../../docs_src/query_params/tutorial002_py310.py hl[7] *} @@ -67,18 +67,17 @@ http://127.0.0.1:8000/items/?skip=20 /// check | Примітка -Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це query параметр. +Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це параметр query. /// -## Перетворення типу Query параметра +## Перетворення типу параметра query { #query-parameter-type-conversion } Ви також можете оголошувати параметри типу `bool`, і вони будуть автоматично конвертовані: {* ../../docs_src/query_params/tutorial003_py310.py hl[7] *} -У цьому випадку, якщо Ви звернетесь до: - +У цьому випадку, якщо ви перейдете за: ``` http://127.0.0.1:8000/items/foo?short=1 @@ -108,38 +107,38 @@ http://127.0.0.1:8000/items/foo?short=on http://127.0.0.1:8000/items/foo?short=yes ``` -або будь-який інший варіант написання (великі літери, перша літера велика тощо), ваша функція побачить параметр `short` зі значенням `True` з типом даних `bool`. В іншому випадку – `False`. +або будь-який інший варіант написання (великі літери, перша літера велика тощо), ваша функція побачить параметр `short` зі значенням `True` типу `bool`. В іншому випадку — `False`. -## Кілька path і query параметрів -Ви можете одночасно оголошувати кілька path і query параметрів, і **FastAPI** автоматично визначить, який з них до чого належить. +## Кілька path і query параметрів { #multiple-path-and-query-parameters } +Ви можете одночасно оголошувати кілька параметрів шляху та параметрів query, **FastAPI** знає, який з них який. -Не потрібно дотримуватись певного порядку їх оголошення. +І вам не потрібно оголошувати їх у якомусь конкретному порядку. Вони визначаються за назвою: {* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *} -## Обов’язкові Query параметри +## Обов’язкові параметри query { #required-query-parameters } -Якщо Ви оголошуєте значення за замовчуванням для параметрів, які не є path-параметрами (у цьому розділі ми бачили поки що лише path параметри), тоді вони стають необов’язковими. +Коли ви оголошуєте значення за замовчуванням для не-path-параметрів (поки що ми бачили лише параметри query), тоді вони не є обов’язковими. -Якщо Ви не хочете вказувати конкретні значення, але хочете зробити параметр опціональним, задайте `None` як значення за замовчуванням. +Якщо ви не хочете задавати конкретне значення, а просто зробити параметр необов’язковим, задайте `None` як значення за замовчуванням. -Але якщо Ви хочете зробити query параметр обов’язковим, просто не вказуйте для нього значення за замовчуванням: +Але якщо ви хочете зробити параметр query обов’язковим, просто не вказуйте для нього значення за замовчуванням: -{* ../../docs_src/query_params/tutorial005.py hl[6:7] *} +{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *} -Тут `needy` – обов’язковий query параметр типу `str`. +Тут параметр query `needy` — обов’язковий параметр query типу `str`. -Якщо Ви відкриєте у браузері URL-адресу: +Якщо ви відкриєте у браузері URL-адресу: ``` http://127.0.0.1:8000/items/foo-item ``` -...без додавання обов’язкового параметра `needy`, Ви побачите помилку: +...без додавання обов’язкового параметра `needy`, ви побачите помилку на кшталт: ```JSON { @@ -163,7 +162,7 @@ http://127.0.0.1:8000/items/foo-item http://127.0.0.1:8000/items/foo-item?needy=sooooneedy ``` -...цей запит поверне: +...це спрацює: ```JSON { @@ -172,20 +171,18 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy } ``` - -Звичайно, Ви можете визначити деякі параметри як обов’язкові, інші зі значенням за замовчуванням, а ще деякі — повністю опціональні: +І звісно, ви можете визначити деякі параметри як обов’язкові, деякі — зі значенням за замовчуванням, а деякі — повністю необов’язкові: {* ../../docs_src/query_params/tutorial006_py310.py hl[8] *} -У цьому випадку є 3 query параметри: +У цьому випадку є 3 параметри query: * `needy`, обов’язковий `str`. * `skip`, `int` зі значенням за замовчуванням `0`. -* `limit`, опціональний `int`. - +* `limit`, необов’язковий `int`. -/// tip | Підказка +/// tip | Порада -Ви також можете використовувати `Enum`-и, так само як і з [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}. +Ви також можете використовувати `Enum` так само, як і з [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}. /// diff --git a/docs/uk/docs/tutorial/request-files.md b/docs/uk/docs/tutorial/request-files.md index 18b7cc01c9..a6ff70dc09 100644 --- a/docs/uk/docs/tutorial/request-files.md +++ b/docs/uk/docs/tutorial/request-files.md @@ -1,56 +1,56 @@ -# Запит файлів +# Запит файлів { #request-files } Ви можете визначити файли, які будуть завантажуватися клієнтом, використовуючи `File`. /// info | Інформація -Щоб отримувати завантажені файли, спочатку встановіть python-multipart. +Щоб отримувати завантажені файли, спочатку встановіть `python-multipart`. -Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його та встановили пакет, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад: ```console $ pip install python-multipart ``` -Це необхідно, оскільки завантажені файли передаються у вигляді "форматованих даних форми". +Це необхідно, оскільки завантажені файли передаються у вигляді «form data». /// -## Імпорт `File` +## Імпорт `File` { #import-file } Імпортуйте `File` та `UploadFile` з `fastapi`: {* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *} -## Визначення параметрів `File` +## Визначення параметрів `File` { #define-file-parameters } -Створіть параметри файлів так само як Ви б створювали `Body` або `Form`: +Створіть параметри файлів так само як ви б створювали `Body` або `Form`: {* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *} /// info | Інформація -`File` — це клас, який безпосередньо успадковує `Form`. +`File` — це клас, який безпосередньо успадковує `Form`. -Але пам’ятайте, що коли Ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи. +Але пам’ятайте, що коли ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи. /// -/// tip | Підказка +/// tip | Порада -Щоб оголосити тіла файлів, Вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON). +Щоб оголосити тіла файлів, вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON). /// -Файли будуть завантажені у вигляді "форматованих даних форми". +Файли будуть завантажені у вигляді «form data». -Якщо Ви оголосите тип параметра функції обробника маршруту як `bytes`, **FastAPI** прочитає файл за Вас, і Ви отримаєте його вміст у вигляді `bytes`. +Якщо ви оголосите тип параметра *функції операції шляху* як `bytes`, **FastAPI** прочитає файл за вас, і ви отримаєте його вміст у вигляді `bytes`. -Однак майте на увазі, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів. +Майте на увазі, що це означає, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів. -Але в деяких випадках Вам може знадобитися `UploadFile`. +Але є кілька випадків, у яких вам може бути корисно використовувати `UploadFile`. -## Параметри файлу з `UploadFile` +## Параметри файлу з `UploadFile` { #file-parameters-with-uploadfile } Визначте параметр файлу з типом `UploadFile`: @@ -59,38 +59,39 @@ $ pip install python-multipart Використання `UploadFile` має кілька переваг перед `bytes`: * Вам не потрібно використовувати `File()` у значенні за замовчуванням параметра. -* Використовується "буферизований" файл: - * Файл зберігається в пам'яті до досягнення певного обмеження, після чого він записується на диск. -* Це означає, що він добре працює для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять. -Ви можете отримати метадані про завантажений файл. -* Він має file-like `асинхронний файловий інтерфейс` interface. -* Він надає фактичний об'єкт Python `SpooledTemporaryFile`, який можна передавати безпосередньо іншим бібліотекам. +* Використовується «spooled» файл: + * Файл зберігається в пам'яті до досягнення максимального обмеження розміру, після чого він буде збережений на диску. +* Це означає, що він добре працюватиме для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять. +* Ви можете отримати метадані про завантажений файл. +* Він має file-like `async` інтерфейс. +* Він надає фактичний об'єкт Python `SpooledTemporaryFile`, який можна передавати безпосередньо іншим бібліотекам, що очікують file-like об'єкт. -### `UploadFile` +### `UploadFile` { #uploadfile } `UploadFile` має такі атрибути: * `filename`: Рядок `str` з оригінальною назвою файлу, який був завантажений (наприклад, `myimage.jpg`). -* `content_type`: Рядок `str` з MIME-типом (наприклад, `image/jpeg`). -* `file`: Об'єкт SpooledTemporaryFile (файлоподібний об'єкт). Це фактичний файловий об'єкт Python, який можна безпосередньо передавати іншим функціям або бібліотекам, що очікують "файлоподібний" об'єкт. +* `content_type`: Рядок `str` з типом вмісту (MIME type / media type) (наприклад, `image/jpeg`). +* `file`: `SpooledTemporaryFile` (file-like об'єкт). Це фактичний файловий об'єкт Python, який ви можете передавати безпосередньо іншим функціям або бібліотекам, що очікують «file-like» об'єкт. -`UploadFile` має такі асинхронні `async` методи. Вони викликають відповідні методи файлу під капотом (використовуючи внутрішній `SpooledTemporaryFile`). +`UploadFile` має такі асинхронні `async` методи. Вони всі викликають відповідні методи файлу під капотом (використовуючи внутрішній `SpooledTemporaryFile`). * `write(data)`: Записує `data` (`str` або `bytes`) у файл. * `read(size)`: Читає `size` (`int`) байтів/символів з файлу. -* `seek(offset)`: Переміщується до позиції `offset` (`int`) у файлі. - * Наприклад, `await myfile.seek(0)` поверне курсор на початок файлу. - * This is especially useful if you run `await myfile.read()` once and then need to read the contents again. Це особливо корисно, якщо Ви виконуєте await `await myfile.read()` один раз, а потім потрібно знову прочитати вміст. +* `seek(offset)`: Переходить до байтової позиції `offset` (`int`) у файлі. + * Наприклад, `await myfile.seek(0)` перейде на початок файлу. + * Це особливо корисно, якщо ви виконаєте `await myfile.read()` один раз, а потім потрібно знову прочитати вміст. * `close()`: Закриває файл. -Оскільки всі ці методи є асинхронними `async`, Вам потрібно використовувати "await": +Оскільки всі ці методи є асинхронними `async` методами, вам потрібно їх «await»-ити. -Наприклад, всередині `async` *функції обробки шляху* Ви можете отримати вміст за допомогою: +Наприклад, всередині `async` *функції операції шляху* ви можете отримати вміст за допомогою: ```Python contents = await myfile.read() ``` -Якщо Ви знаходитесь у звичайній `def` *функції обробки шляху*, Ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад: + +Якщо ви знаходитесь у звичайній `def` *функції операції шляху*, ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад: ```Python contents = myfile.file.read() @@ -98,57 +99,57 @@ contents = myfile.file.read() /// note | Технічні деталі `async` -Коли Ви використовуєте `async` методи, **FastAPI** виконує файлові операції у пулі потоків та очікує їх завершення. +Коли ви використовуєте `async` методи, **FastAPI** виконує файлові методи у пулі потоків і очікує на них. /// /// note | Технічні деталі Starlette -`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими компонентами FastAPI. +`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими частинами FastAPI. /// -## Що таке "Form Data" +## Що таке «Form Data» { #what-is-form-data } -Спосіб, у який HTML-форми (`
`) надсилають дані на сервер, зазвичай використовує "спеціальне" кодування, відмінне від JSON. +Спосіб, у який HTML-форми (`
`) надсилають дані на сервер, зазвичай використовує «спеціальне» кодування для цих даних, відмінне від JSON. -**FastAPI** забезпечує правильне зчитування цих даних з відповідної частини запиту, а не з JSON. +**FastAPI** забезпечить зчитування цих даних з правильного місця, а не з JSON. /// note | Технічні деталі -Дані з форм зазвичай кодуються за допомогою "media type" `application/x-www-form-urlencoded`, якщо вони не містять файлів. +Дані з форм зазвичай кодуються за допомогою «media type» `application/x-www-form-urlencoded`, якщо вони не містять файлів. -Але якщо форма містить файли, вона кодується у форматі `multipart/form-data`. Якщо Ви використовуєте `File`, **FastAPI** визначить, що потрібно отримати файли з відповідної частини тіла запиту. +Але якщо форма містить файли, вона кодується як `multipart/form-data`. Якщо ви використовуєте `File`, **FastAPI** знатиме, що потрібно отримати файли з правильної частини тіла. -Щоб дізнатися більше про ці типи кодування та формові поля, ознайомтеся з документацією MDN щодо POST. +Якщо ви хочете дізнатися більше про ці типи кодування та формові поля, ознайомтеся з MDN web docs для POST. /// -/// warning | Увага +/// warning | Попередження -Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але Ви не можете одночасно оголошувати поля `Body`, які мають надходити у форматі JSON, оскільки тіло запиту буде закодоване у форматі `multipart/form-data`, а не `application/json`. +Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але ви не можете одночасно оголошувати поля `Body`, які ви очікуєте отримати як JSON, оскільки запит матиме тіло, закодоване як `multipart/form-data`, а не `application/json`. -Це не обмеження **FastAPI**, а особливість протоколу HTTP. +Це не обмеження **FastAPI**, а частина протоколу HTTP. /// -## Опціональне Завантаження Файлів +## Необов’язкове завантаження файлу { #optional-file-upload } -Файл можна зробити необов’язковим, використовуючи стандартні анотації типів і встановлюючи значення за замовчуванням `None`: +Ви можете зробити файл необов’язковим, використовуючи стандартні анотації типів і встановивши значення за замовчуванням `None`: {* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *} -## `UploadFile` із Додатковими Мета Даними +## `UploadFile` із додатковими метаданими { #uploadfile-with-additional-metadata } -Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, для встановлення додаткових метаданих: +Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, щоб встановити додаткові метадані: {* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *} -## Завантаження Кількох Файлів +## Завантаження кількох файлів { #multiple-file-uploads } Можна завантажувати кілька файлів одночасно. -Вони будуть пов’язані з одним і тим самим "form field", який передається у вигляді "form data". +Вони будуть пов’язані з одним і тим самим «form field», який передається у вигляді «form data». Щоб це реалізувати, потрібно оголосити список `bytes` або `UploadFile`: @@ -160,16 +161,16 @@ contents = myfile.file.read() Ви також можете використати `from starlette.responses import HTMLResponse`. -**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, для зручності розробників. Однак більшість доступних відповідей надходять безпосередньо від Starlette. +**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо від Starlette. /// -### Завантаження декількох файлів із додатковими метаданими +### Завантаження кількох файлів із додатковими метаданими { #multiple-file-uploads-with-additional-metadata } -Так само як і раніше, Ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`: +Так само як і раніше, ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`: {* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *} -## Підсумок +## Підсумок { #recap } -Використовуйте `File`, `bytes`та `UploadFile`, щоб оголошувати файли для завантаження у запитах, які надсилаються у вигляді form data. +Використовуйте `File`, `bytes` та `UploadFile`, щоб оголошувати файли для завантаження в запиті, надіслані у вигляді form data. diff --git a/docs/uk/docs/tutorial/request-form-models.md b/docs/uk/docs/tutorial/request-form-models.md index 7f5759e79a..1bfd368d60 100644 --- a/docs/uk/docs/tutorial/request-form-models.md +++ b/docs/uk/docs/tutorial/request-form-models.md @@ -1,12 +1,12 @@ -# Моделі форм (Form Models) +# Моделі форм { #form-models } -У FastAPI Ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**. +У FastAPI ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**. /// info | Інформація -Щоб використовувати форми, спочатку встановіть python-multipart. +Щоб використовувати форми, спочатку встановіть `python-multipart`. -Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили його, наприклад: ```console $ pip install python-multipart @@ -14,21 +14,21 @@ $ pip install python-multipart /// -/// note | Підказка +/// note | Примітка -Ця функція підтримується, починаючи з FastAPI версії `0.113.0`. 🤓 +Це підтримується, починаючи з FastAPI версії `0.113.0`. 🤓 /// -## Використання Pydantic-моделей для форм +## Pydantic-моделі для форм { #pydantic-models-for-forms } -Вам просто потрібно оголосити **Pydantic-модель** з полями, які Ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`: +Вам просто потрібно оголосити **Pydantic-модель** з полями, які ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`: {* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *} -**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку Ви визначили. +**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку ви визначили. -## Перевірка документації +## Перевірте документацію { #check-the-docs } Ви можете перевірити це в UI документації за `/docs`: @@ -36,13 +36,13 @@ $ pip install python-multipart -## Заборона додаткових полів форми +## Забороніть додаткові поля форми { #forbid-extra-form-fields } -У деяких особливих випадках (ймовірно, рідко) Ви можете **обмежити** форму лише тими полями, які були оголошені в Pydantic-моделі, і **заборонити** будь-які **додаткові** поля. +У деяких особливих випадках (ймовірно, не дуже поширених) ви можете **обмежити** поля форми лише тими, які були оголошені в Pydantic-моделі. І **заборонити** будь-які **додаткові** поля. -/// note | Підказка +/// note | Примітка -Ця функція підтримується, починаючи з FastAPI версії `0.114.0`. 🤓 +Це підтримується, починаючи з FastAPI версії `0.114.0`. 🤓 /// @@ -52,7 +52,7 @@ $ pip install python-multipart Якщо клієнт спробує надіслати додаткові дані, він отримає **відповідь з помилкою**. -Наприклад, якщо клієнт спробує надіслати наступні поля форми: +Наприклад, якщо клієнт спробує надіслати поля форми: * `username`: `Rick` * `password`: `Portal Gun` @@ -73,6 +73,6 @@ $ pip install python-multipart } ``` -## Підсумок +## Підсумок { #summary } -Ви можете використовувати Pydantic-моделі для оголошення полів форми у FastAPI. 😎 +У FastAPI ви можете використовувати Pydantic-моделі для оголошення полів форми. 😎 diff --git a/docs/uk/docs/tutorial/request-forms-and-files.md b/docs/uk/docs/tutorial/request-forms-and-files.md index a089ef945a..e809bee225 100644 --- a/docs/uk/docs/tutorial/request-forms-and-files.md +++ b/docs/uk/docs/tutorial/request-forms-and-files.md @@ -1,10 +1,10 @@ -# Запити з формами та файлами +# Запити з формами та файлами { #request-forms-and-files } -У FastAPI Ви можете одночасно отримувати файли та поля форми, використовуючи `File` і `Form`. +Ви можете одночасно визначати файли та поля форми, використовуючи `File` і `Form`. /// info | Інформація -Щоб отримувати завантажені файли та/або дані форми, спочатку встановіть python-multipart. +Щоб отримувати завантажені файли та/або дані форми, спочатку встановіть `python-multipart`. Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад: @@ -14,21 +14,21 @@ $ pip install python-multipart /// -## Імпорт `File` та `Form` +## Імпорт `File` та `Form` { #import-file-and-form } {* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *} -## Оголошення параметрів `File` та `Form` +## Оголошення параметрів `File` та `Form` { #define-file-and-form-parameters } Створіть параметри файлів та форми так само як і для `Body` або `Query`: {* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *} -Файли та поля форми будуть завантажені як формові дані, і Ви отримаєте як файли, так і введені користувачем поля. +Файли та поля форми будуть завантажені як формові дані, і Ви отримаєте файли та поля форми. Ви також можете оголосити деякі файли як `bytes`, а деякі як `UploadFile`. -/// warning | Увага +/// warning | Попередження Ви можете оголосити кілька параметрів `File` і `Form` в операції *шляху*, але не можете одночасно оголошувати `Body`-поля, які очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване за допомогою `multipart/form-data`, а не `application/json`. @@ -36,6 +36,6 @@ $ pip install python-multipart /// -## Підсумок +## Підсумок { #recap } -Використовуйте `File` та `Form` разом, коли вам потрібно отримувати дані форми та файли в одному запиті. +Використовуйте `File` та `Form` разом, коли вам потрібно отримувати дані та файли в одному запиті. diff --git a/docs/uk/docs/tutorial/request-forms.md b/docs/uk/docs/tutorial/request-forms.md index 10c58a73e4..2a22ad922a 100644 --- a/docs/uk/docs/tutorial/request-forms.md +++ b/docs/uk/docs/tutorial/request-forms.md @@ -1,12 +1,12 @@ -# Дані форми +# Дані форми { #form-data } -Якщо Вам потрібно отримувати поля форми замість JSON, Ви можете використовувати `Form`. +Якщо вам потрібно отримувати поля форми замість JSON, ви можете використовувати `Form`. /// info | Інформація Щоб використовувати форми, спочатку встановіть `python-multipart`. -Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, і потім встановили бібліотеку, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, і потім встановили бібліотеку, наприклад: ```console $ pip install python-multipart @@ -14,23 +14,23 @@ $ pip install python-multipart /// -## Імпорт `Form` +## Імпорт `Form` { #import-form } Імпортуйте `Form` з `fastapi`: {* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *} -## Оголошення параметрів `Form` +## Оголошення параметрів `Form` { #define-form-parameters } -Створюйте параметри форми так само як Ви б створювали `Body` або `Query`: +Створюйте параметри форми так само як ви б створювали `Body` або `Query`: {* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *} Наприклад, один зі способів використання специфікації OAuth2 (так званий "password flow") вимагає надсилати `username` та `password` як поля форми. -spec вимагає, щоб ці поля мали точні назви `username` і `password` та надсилалися у вигляді полів форми, а не JSON. +spec вимагає, щоб ці поля мали точні назви `username` і `password` та надсилалися у вигляді полів форми, а не JSON. -З `Form` Ви можете оголошувати ті ж конфігурації, що і з `Body` (та `Query`, `Path`, `Cookie`), включаючи валідацію, приклади, псевдоніми (наприклад, `user-name` замість `username`) тощо. +З `Form` ви можете оголошувати ті ж конфігурації, що і з `Body` (та `Query`, `Path`, `Cookie`), включаючи валідацію, приклади, псевдоніми (наприклад, `user-name` замість `username`) тощо. /// info | Інформація @@ -44,7 +44,7 @@ $ pip install python-multipart /// -## Про "поля форми" +## Про "поля форми" { #about-form-fields } HTML-форми (`
`) надсилають дані на сервер у "спеціальному" кодуванні, яке відрізняється від JSON. @@ -56,18 +56,18 @@ HTML-форми (`
`) надсилають дані на серве Але якщо форма містить файли, вона кодується як `multipart/form-data`. Ви дізнаєтеся про обробку файлів у наступному розділі. -Якщо Ви хочете дізнатися більше про ці кодування та поля форм, зверніться до MDN вебдокументації для POST. +Якщо ви хочете дізнатися більше про ці кодування та поля форм, зверніться до MDN вебдокументації для POST. /// /// warning | Попередження -Ви можете оголосити кілька параметрів `Form` в *операції шляху*, але не можете одночасно оголосити поля `Body`, які Ви очікуєте отримати у форматі JSON, оскільки тіло запиту буде закодовано у форматі `application/x-www-form-urlencoded`, а не `application/json`. +Ви можете оголосити кілька параметрів `Form` в *операції шляху*, але не можете одночасно оголосити поля `Body`, які ви очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване як `application/x-www-form-urlencoded`, а не `application/json`. Це не обмеження **FastAPI**, а частина HTTP-протоколу. /// -## Підсумок +## Підсумок { #recap } Використовуйте `Form` для оголошення вхідних параметрів у вигляді даних форми. diff --git a/docs/uk/docs/tutorial/response-model.md b/docs/uk/docs/tutorial/response-model.md index def1f8a2d5..2fcad94387 100644 --- a/docs/uk/docs/tutorial/response-model.md +++ b/docs/uk/docs/tutorial/response-model.md @@ -1,36 +1,35 @@ -# Модель відповіді — Тип, що повертається +# Модель відповіді — Тип, що повертається { #response-model-return-type } -Ви можете оголосити тип, який використовуватиметься у відповіді, за допомогою *анотації типу, що повертається* *функцією операцією шляху* (path operation) +Ви можете оголосити тип, який використовуватиметься у відповіді, анотувавши **тип повернення** *функції операції шляху*. -**Анотацію типу** можна вказати так само як і для вхідних **параметрів** функції: це можуть бути моделі Pydantic, списки (lists), словники (dictionaries), скалярні значення, як-от цілі числа (integers), булеві значення (booleans) тощо. +**Анотації типів** можна використовувати так само, як і для вхідних даних у **параметрах** функції: можна використовувати моделі Pydantic, списки, словники, скалярні значення, як-от цілі числа, булеві значення тощо. {* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} -FastAPI використовуватиме цей тип, щоб: +FastAPI використовуватиме цей тип повернення, щоб: * **Перевірити правильність** повернених даних. - * Якщо дані не валідні (наприклад, відсутнє поле), це означає, що Ваш код додатку працює некоректно і не повертає те, що повинен. У такому випадку FastAPI поверне помилку сервера, замість того щоб віддати недопустимі дані. Так Ви та Ваші клієнти будете впевнені, що отримуєте очікувані дані у правильному форматі. - -* Додати **JSON Schema** відповіді до специфікації OpenAPI в *операціях шляху*. + * Якщо дані не валідні (наприклад, відсутнє поле), це означає, що *ваш* код застосунку зламаний, не повертає те, що повинен, і буде повернуто помилку сервера замість некоректних даних. Так ви та ваші клієнти можете бути впевнені, що отримаєте дані й очікувану структуру даних. +* Додати **JSON Schema** для відповіді в OpenAPI *операції шляху*. * Це буде використано в **автоматичній документації**. - * А також інструментами, які автоматично генерують клієнтський код. + * Це також буде використано інструментами, які автоматично генерують клієнтський код. Але найголовніше: -* FastAPI **обмежить та відфільтрує** вихідні дані відповідно до типу, вказаного у відповіді. - * Це особливо важливо для **безпеки**. Деталі нижче. +* Це **обмежить та відфільтрує** вихідні дані до того, що визначено в типі повернення. + * Це особливо важливо для **безпеки**, нижче ми побачимо про це більше. -## Параметр `response_model` +## Параметр `response_model` { #response-model-parameter } -Іноді Вам потрібно або зручно повертати інші типи даних, ніж ті, що зазначені як тип відповіді. +Є випадки, коли вам потрібно або ви хочете повертати дані, які не зовсім відповідають тому, що оголошено типом. -Наприклад, Ви можете **повертати словник** або об’єкт бази даних, але **оголосити модель Pydantic** як модель відповіді. Тоді модель Pydantic автоматично оброблятиме валідацію, документацію тощо. +Наприклад, ви можете захотіти **повертати словник** або об’єкт бази даних, але **оголосити його як модель Pydantic**. Таким чином модель Pydantic виконуватиме всю документацію даних, валідацію тощо для об’єкта, який ви повернули (наприклад, словника або об’єкта бази даних). -Якщо Ви додасте анотацію типу для повернення, редактор коду або mypy можуть поскаржитися, що функція повертає інший тип (наприклад, dict замість Item). +Якщо ви додали анотацію типу повернення, інструменти та редактори скаржитимуться (коректною) помилкою, повідомляючи, що ваша функція повертає тип (наприклад, dict), який відрізняється від того, що ви оголосили (наприклад, модель Pydantic). -У таких випадках можна скористатися параметром `response_model` в декораторі маршруту (наприклад, @app.get()). +У таких випадках можна скористатися параметром *декоратора операції шляху* `response_model` замість типу повернення. -Параметр `response_model` працює з будь-яким *оператором шляху*: +Ви можете використовувати параметр `response_model` у будь-якій з *операцій шляху*: * `@app.get()` * `@app.post()` @@ -42,33 +41,33 @@ FastAPI використовуватиме цей тип, щоб: /// note | Примітка -Зверніть увагу, що `response_model` є параметром методу-декоратора (`get`, `post`, тощо), а не *функцією операцією шляху* (path operation function), як це робиться з параметрами або тілом запиту. +Зверніть увагу, що `response_model` є параметром методу «декоратора» (`get`, `post` тощо). А не вашої *функції операції шляху*, як усі параметри та тіло. /// -`response_model` приймає такий самий тип, який Ви б вказали для поля моделі Pydantic. Тобто це може бути як Pydantic-модель, так і, наприклад, `list` із моделей Pydantic — `List[Item]`. +`response_model` приймає такий самий тип, який ви б вказали для поля моделі Pydantic, тобто це може бути модель Pydantic, але також це може бути, наприклад, `list` моделей Pydantic, як-от `List[Item]`. -FastAPI використовуватиме `response_model` для створення документації, валідації даних та — найважливіше — **перетворення та фільтрації вихідних даних** згідно з оголошеним типом. +FastAPI використовуватиме цей `response_model` для виконання всієї документації даних, валідації тощо, а також для **перетворення та фільтрації вихідних даних** до оголошеного типу. /// tip | Порада -Якщо у Вас увімкнено сувору перевірку типів у редакторі, mypy тощо, Ви можете оголосити тип повернення функції як `Any`. +Якщо у вас увімкнено сувору перевірку типів у редакторі, mypy тощо, ви можете оголосити тип повернення функції як `Any`. -Таким чином, Ви повідомляєте редактору, що свідомо повертаєте будь-що. Але FastAPI усе одно виконуватиме створення документації, валідацію, фільтрацію тощо за допомогою параметра `response_model`. +Таким чином, ви повідомляєте редактору, що свідомо повертаєте будь-що. Але FastAPI усе одно виконуватиме документацію даних, валідацію, фільтрацію тощо за допомогою `response_model`. /// -### Пріоритет `response_model` +### Пріоритет `response_model` { #response-model-priority } -Якщо Ви вказуєте і тип повернення, і `response_model`, то FastAPI використовуватиме `response_model` з пріоритетом. +Якщо ви оголошуєте і тип повернення, і `response_model`, то `response_model` матиме пріоритет і буде використаний FastAPI. -Таким чином, Ви можете додати правильні анотації типів до ваших функцій, навіть якщо вони повертають тип, відмінний від `response_model`. Це буде корисно для редакторів коду та інструментів, таких як mypy. І при цьому FastAPI продовжить виконувати валідацію даних, генерувати документацію тощо на основі `response_model`. +Таким чином ви можете додати правильні анотації типів до ваших функцій, навіть коли повертаєте тип, відмінний від моделі відповіді, щоб це використовували редактор і інструменти на кшталт mypy. І при цьому FastAPI все одно виконуватиме валідацію даних, документацію тощо, використовуючи `response_model`. -Ви також можете використати `response_model=None`, щоб вимкнути створення моделі відповіді для цієї *операції шляху*. Це може знадобитися, якщо Ви додаєте анотації типів до об'єктів, які не є допустимими полями Pydantic — приклад цього Ви побачите в одному з наступних розділів. +Ви також можете використати `response_model=None`, щоб вимкнути створення моделі відповіді для цієї *операції шляху*; це може знадобитися, якщо ви додаєте анотації типів для речей, які не є валідними полями Pydantic, приклад цього ви побачите в одному з розділів нижче. -## Повернути ті самі вхідні дані +## Повернути ті самі вхідні дані { #return-the-same-input-data } -Тут ми оголошуємо модель `UserIn`, яка містить звичайний текстовий пароль: +Тут ми оголошуємо модель `UserIn`, вона міститиме пароль у відкритому вигляді: {* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *} @@ -76,7 +75,7 @@ FastAPI використовуватиме `response_model` для створе Щоб використовувати `EmailStr`, спочатку встановіть `email-validator`. -Переконайтесь, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад: ```console $ pip install email-validator @@ -90,29 +89,29 @@ $ pip install "pydantic[email]" /// -І ми використовуємо цю модель, щоб оголосити і вхідні, і вихідні дані: +І ми використовуємо цю модель, щоб оголосити наші вхідні дані, і цю ж модель, щоб оголосити наші вихідні дані: {* ../../docs_src/response_model/tutorial002_py310.py hl[16] *} -Тепер, коли браузер створює користувача з паролем, API поверне той самий пароль у відповіді. +Тепер, щоразу коли браузер створює користувача з паролем, API поверне той самий пароль у відповіді. -У цьому випадку це може не бути проблемою, адже саме користувач надіслав пароль. +У цьому випадку це може не бути проблемою, адже це той самий користувач надсилає пароль. -Але якщо ми використаємо цю ж модель для іншої операції шляху, ми можемо випадково надіслати паролі наших користувачів кожному клієнту. +Але якщо ми використаємо цю ж модель для іншої *операції шляху*, ми можемо надсилати паролі наших користувачів кожному клієнту. /// danger | Обережно -Ніколи не зберігайте пароль користувача у відкритому вигляді та не надсилайте його у відповіді, якщо тільки Ви не знаєте всі ризики і точно розумієте, що робите. +Ніколи не зберігайте пароль користувача у відкритому вигляді та не надсилайте його у відповіді таким чином, якщо тільки ви не знаєте всіх застережень і точно розумієте, що робите. /// -## Додайте окрему вихідну модель +## Додати вихідну модель { #add-an-output-model } -Замість цього ми можемо створити вхідну модель з відкритим паролем і вихідну модель без нього: +Замість цього ми можемо створити вхідну модель з паролем у відкритому вигляді і вихідну модель без нього: {* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *} -Тут, навіть якщо *функція операції шляху* повертає об'єкт користувача, який містить пароль: +Тут, хоча наша *функція операції шляху* повертає того самого вхідного користувача, який містить пароль: {* ../../docs_src/response_model/tutorial003_py310.py hl[24] *} @@ -120,107 +119,107 @@ $ pip install "pydantic[email]" {* ../../docs_src/response_model/tutorial003_py310.py hl[22] *} -Таким чином, **FastAPI** автоматично відфільтрує всі дані, які не вказані у вихідній моделі (за допомогою Pydantic). +Таким чином, **FastAPI** подбає про фільтрацію всіх даних, які не оголошені у вихідній моделі (використовуючи Pydantic). -### `response_model` або тип повернення +### `response_model` або тип повернення { #response-model-or-return-type } -У цьому випадку, оскільки дві моделі різні, якщо ми анотуємо тип повернення функції як `UserOut`, редактор і такі інструменти, як mypy, видадуть помилку, бо фактично ми повертаємо інший тип. +У цьому випадку, оскільки дві моделі різні, якщо ми анотуємо тип повернення функції як `UserOut`, редактор і інструменти скаржитимуться, що ми повертаємо невалідний тип, адже це різні класи. -Тому в цьому прикладі ми використовуємо параметр `response_model`, а не анотацію типу повернення. +Саме тому в цьому прикладі нам треба оголосити це через параметр `response_model`. -...але читайте далі, щоб дізнатися, як обійти це обмеження. +...але читайте далі нижче, щоб побачити, як це обійти. -## Тип повернення і фільтрація даних +## Тип повернення і фільтрація даних { #return-type-and-data-filtering } -Продовжимо з попереднього прикладу. Ми хотіли **анотувати функцію одним типом**, але при цьому повертати з неї більше даних. +Продовжимо з попереднього прикладу. Ми хотіли **анотувати функцію одним типом**, але хотіли мати змогу повертати з функції те, що насправді містить **більше даних**. -Ми хочемо, щоб FastAPI продовжував **фільтрувати** ці дані за допомогою response_model. Тобто навіть якщо функція повертає більше інформації, у відповіді будуть лише ті поля, які вказані у response_model. +Ми хочемо, щоб FastAPI продовжував **фільтрувати** дані, використовуючи модель відповіді. Тобто навіть якщо функція повертає більше даних, відповідь міститиме лише поля, оголошені в моделі відповіді. -У попередньому прикладі, оскільки класи були різні, нам довелося використовувати параметр `response_model`. Але це означає, що ми не отримуємо підтримки з боку редактора коду та інструментів перевірки типів щодо типу, який повертає функція. +У попередньому прикладі, оскільки класи були різні, нам довелося використовувати параметр `response_model`. Але це також означає, що ми не отримуємо підтримки від редактора та інструментів, які перевіряють тип повернення функції. -Проте в більшості випадків, коли нам потрібно зробити щось подібне, ми просто хочемо, щоб модель **відфільтрувала або прибрала** частину даних, як у цьому прикладі. +Проте в більшості випадків, коли нам потрібно зробити щось подібне, ми просто хочемо, щоб модель **відфільтрувала/прибрала** частину даних, як у цьому прикладі. -У таких випадках ми можемо використати класи та спадкування, щоб скористатися **анотаціями типів** функцій — це дає кращу підтримку з боку редактора та інструментів типу mypy, і при цьому FastAPI продовжує виконувати **фільтрацію даних** у відповіді. +І в таких випадках ми можемо використати класи та спадкування, щоб скористатися **анотаціями типів** функцій і отримати кращу підтримку в редакторі та інструментах, і при цьому зберегти **фільтрацію даних** у FastAPI. {* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *} -Завдяки цьому ми отримуємо підтримку інструментів — від редакторів і mypy, оскільки цей код є коректним з точки зору типів, — але ми також отримуємо фільтрацію даних від FastAPI. +Завдяки цьому ми отримуємо підтримку інструментів — від редакторів і mypy, адже цей код коректний з точки зору типів, — але ми також отримуємо фільтрацію даних від FastAPI. Як це працює? Давайте розберемося. 🤓 -### Типи та підтримка інструментів +### Анотації типів і підтримка інструментів { #type-annotations-and-tooling } -Спершу подивимось, як це бачать редактори, mypy та інші інструменти. +Спершу подивімося, як це бачать редактори, mypy та інші інструменти. -`BaseUser` має базові поля. Потім `UserIn` успадковує `BaseUser` і додає поле `password`, отже, він матиме всі поля з обох моделей. +`BaseUser` має базові поля. Потім `UserIn` успадковує `BaseUser` і додає поле `password`, отже він включатиме всі поля з обох моделей. -Ми зазначаємо тип повернення функції як `BaseUser`, але фактично повертаємо екземпляр `UserIn`. +Ми анотуємо тип повернення функції як `BaseUser`, але фактично повертаємо екземпляр `UserIn`. -Редактор, mypy та інші інструменти не скаржитимуться на це, тому що з точки зору типізації `UserIn` є підкласом `BaseUser`, а це означає, що він є `валідним` типом, коли очікується будь-що, що є `BaseUser`. +Редактор, mypy та інші інструменти не скаржитимуться на це, тому що з точки зору типізації `UserIn` є підкласом `BaseUser`, а це означає, що він є *валідним* типом, коли очікується будь-що, що є `BaseUser`. -### Фільтрація даних у FastAPI +### Фільтрація даних у FastAPI { #fastapi-data-filtering } -Тепер для FastAPI він бачить тип повернення і переконується, що те, що Ви повертаєте, містить **тільки** поля, які оголошені у цьому типі. +Тепер для FastAPI він побачить тип повернення і переконається, що те, що ви повертаєте, містить **лише** поля, які оголошені у цьому типі. -FastAPI виконує кілька внутрішніх операцій з Pydantic, щоб гарантувати, що правила наслідування класів не застосовуються для фільтрації повернених даних, інакше Ви могли б повернути значно більше даних, ніж очікували. +FastAPI виконує кілька внутрішніх операцій з Pydantic, щоб гарантувати, що ті самі правила наслідування класів не застосовуються для фільтрації повернених даних, інакше ви могли б зрештою повертати значно більше даних, ніж очікували. -Таким чином, Ви отримуєте найкраще з двох світів: анотації типів **з підтримкою інструментів** і **фільтрацію даних**. +Таким чином ви можете отримати найкраще з двох світів: анотації типів із **підтримкою інструментів** і **фільтрацію даних**. -## Подивитись у документації +## Подивитися в документації { #see-it-in-the-docs } -Коли Ви дивитесь автоматичну документацію, Ви можете побачити, що вхідна модель і вихідна модель мають власну JSON-схему: +Коли ви дивитеся автоматичну документацію, ви можете перевірити, що вхідна модель і вихідна модель матимуть власну JSON Schema: -І обидві моделі використовуються для інтерактивної API-документації: +І обидві моделі будуть використані для інтерактивної документації API: -## Інші анотації типів повернення +## Інші анотації типів повернення { #other-return-type-annotations } -Існують випадки, коли Ви повертаєте щось, що не є допустимим полем Pydantic, але анотуєте це у функції лише для того, щоб отримати підтримку від інструментів (редактора, mypy тощо). +Можуть бути випадки, коли ви повертаєте щось, що не є валідним полем Pydantic, і анотуєте це у функції лише для того, щоб отримати підтримку від інструментів (редактора, mypy тощо). -### Повернення Response напряму +### Повернути Response напряму { #return-a-response-directly } Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у розширеній документації](../advanced/response-directly.md){.internal-link target=_blank}. -{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *} +{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *} Цей простий випадок автоматично обробляється FastAPI, тому що анотація типу повернення — це клас (або підклас) `Response`. І інструменти також будуть задоволені, бо і `RedirectResponse`, і `JSONResponse` є підкласами `Response`, отже анотація типу коректна. -### Анотація підкласу Response +### Анотувати підклас Response { #annotate-a-response-subclass } -Також можна використовувати підклас `Response` у анотації типу: +Ви також можете використати підклас `Response` в анотації типу: -{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *} +{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *} Це теж працюватиме, бо `RedirectResponse` — підклас `Response`, і FastAPI автоматично обробить цей простий випадок. -### Некоректні анотації типу повернення +### Некоректні анотації типу повернення { #invalid-return-type-annotations } -Але коли Ви повертаєте якийсь інший довільний об’єкт, що не є валідним типом Pydantic (наприклад, об’єкт бази даних), і анотуєте його так у функції, FastAPI спробує створити Pydantic модель відповіді на основі цієї анотації типу, і це завершиться помилкою. +Але коли ви повертаєте якийсь інший довільний об’єкт, що не є валідним типом Pydantic (наприклад, об’єкт бази даних), і анотуєте його так у функції, FastAPI спробує створити модель відповіді Pydantic на основі цієї анотації типу і це завершиться помилкою. -Те саме станеться, якщо Ви використовуєте union між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це спричинить помилку 💥: +Те саме станеться, якщо ви використаєте union між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це завершиться помилкою 💥: {* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *} -...це не працює, тому що тип анотації не є типом Pydantic і не є просто класом `Response` або його підкласом, а є об’єднанням (union) — або `Response`, або `dict`. +...це не працює, тому що анотація типу не є типом Pydantic і не є просто одним класом `Response` або його підкласом, це union (будь-який із двох) між `Response` і `dict`. -### Відключення Моделі Відповіді +### Вимкнути модель відповіді { #disable-response-model } -Продовжуючи приклад вище, можливо, Ви не хочете використовувати стандартну валідацію даних, автоматичну документацію, фільтрацію тощо, які FastAPI виконує за замовчуванням. +Продовжуючи приклад вище, можливо, ви не хочете мати стандартну валідацію даних, документацію, фільтрацію тощо, які виконує FastAPI. -Але ви все одно можете залишити анотацію типу у функції, щоб зберегти підтримку з боку інструментів, таких як редактори коду або статичні перевірки типів (наприклад, mypy). +Але ви можете все одно хотіти залишити анотацію типу повернення у функції, щоб отримати підтримку від інструментів, як-от редактори та перевірки типів (наприклад, mypy). У такому випадку ви можете вимкнути генерацію моделі відповіді, встановивши `response_model=None`: {* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *} -Це змусить FastAPI пропустити генерацію моделі відповіді, і таким чином Ви зможете використовувати будь-які анотації типів повернення без впливу на вашу FastAPI аплікацію. 🤓 +Це змусить FastAPI пропустити генерацію моделі відповіді, і таким чином ви зможете використовувати будь-які потрібні анотації типів повернення без впливу на ваш FastAPI застосунок. 🤓 -## Параметри кодування моделі відповіді +## Параметри кодування моделі відповіді { #response-model-encoding-parameters } Ваша модель відповіді може мати значення за замовчуванням, наприклад: @@ -230,19 +229,19 @@ FastAPI виконує кілька внутрішніх операцій з Pyd * `tax: float = 10.5` має значення за замовчуванням `10.5`. * `tags: List[str] = []` має значення за замовчуванням порожній список: `[]`. -Але Ви можете захотіти не включати їх у результат, якщо вони фактично не були збережені. +але ви можете захотіти не включати їх у результат, якщо вони фактично не були збережені. -Наприклад, якщо у Вас є моделі з багатьма необов’язковими атрибутами у NoSQL базі даних, але Ви не хочете відправляти дуже довгі JSON-відповіді, повні значень за замовчуванням. +Наприклад, якщо у вас є моделі з багатьма необов’язковими атрибутами у NoSQL базі даних, але ви не хочете надсилати дуже довгі JSON-відповіді, повні значень за замовчуванням. -### Використовуйте параметр `response_model_exclude_unset` +### Використовуйте параметр `response_model_exclude_unset` { #use-the-response-model-exclude-unset-parameter } -Ви можете встановити параметр декоратора шляху `response_model_exclude_unset=True`: +Ви можете встановити параметр *декоратора операції шляху* `response_model_exclude_unset=True`: {* ../../docs_src/response_model/tutorial004_py310.py hl[22] *} -і ці значення за замовчуванням не будуть включені у відповідь, тільки фактично встановлені значення. +і ці значення за замовчуванням не будуть включені у відповідь, лише значення, які фактично встановлені. -Отже, якщо Ви надішлете запит до цього оператора шляху для елемента з item_id `foo`, відповідь (без включення значень за замовчуванням) буде: +Отже, якщо ви надішлете запит до цієї *операції шляху* для елемента з ID `foo`, відповідь (без включення значень за замовчуванням) буде: ```JSON { @@ -253,32 +252,18 @@ FastAPI виконує кілька внутрішніх операцій з Pyd /// info | Інформація -У Pydantic версії 1 метод називався `.dict()`, він був застарілий (але ще підтримується) у Pydantic версії 2 і перейменований у `.model_dump()`. - -Приклади тут використовують `.dict()` для сумісності з Pydantic v1, але Вам слід використовувати `.model_dump()`, якщо Ви можете використовувати Pydantic v2. - -/// - -/// info | Інформація - -FastAPI використовує `.dict()` моделі Pydantic з параметром `exclude_unset`, щоб досягти цього. - -/// - -/// info | Інформація - Ви також можете використовувати: * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -як описано в документації Pydantic for `exclude_defaults` та `exclude_none`. +як описано в документації Pydantic для `exclude_defaults` та `exclude_none`. /// -#### Дані зі значеннями для полів із типовими значеннями +#### Дані зі значеннями для полів із типовими значеннями { #data-with-values-for-fields-with-defaults } -Але якщо Ваші дані мають значення для полів моделі з типовими значеннями, як у елемента з item_id `bar`: +Але якщо ваші дані мають значення для полів моделі з типовими значеннями, як у елемента з ID `bar`: ```Python hl_lines="3 5" { @@ -288,11 +273,12 @@ FastAPI використовує `.dict()` моделі Pydantic з `http.HTTPStatus`. + +`status_code` також може, як альтернативу, приймати `IntEnum`, наприклад, Python `http.HTTPStatus`. /// Він буде: -* Повертати вказаний код статусу у відповіді. -* Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсі користувача): +* Повертати цей код статусу у відповіді. +* Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсах користувача): -/// note | Нотатка +/// note | Примітка Деякі коди відповіді (див. наступний розділ) вказують, що відповідь не має тіла. -FastAPI знає про це і створить OpenAPI документацію, яка вказує, що тіла відповіді немає. +FastAPI знає про це і створить документацію OpenAPI, яка вказує, що тіла відповіді немає. /// -## Про HTTP статус коди +## Про HTTP коди статусу { #about-http-status-codes } -/// note | Нотатка +/// note | Примітка -Якщо Ви вже знаєте, що таке HTTP коди статусу, переходьте до наступного розділу. +Якщо ви вже знаєте, що таке HTTP коди статусу, перейдіть до наступного розділу. /// -В HTTP Ви надсилаєте числовий код статусу з 3 цифр як частину відповіді. +В HTTP ви надсилаєте числовий код статусу з 3 цифр як частину відповіді. -Ці коди статусу мають пов’язану назву для їх розпізнавання, але найважливішою частиною є саме число. +Ці коди статусу мають пов’язану назву для їх розпізнавання, але важливою частиною є число. Коротко: -* **`100 - 199`** "Інформаційні" відповіді. Ви рідко використовуєте їх напряму. Відповіді з такими кодами не можуть мати тіла. -* **`200 - 299`** "Успішні" відповіді. Це ті, які Ви використовуватимете найчастіше. - * `200` - код за замовчуванням, який означає, що все пройшло "OK". - * Інший приклад – `201`, "Created" (створено). Його зазвичай використовують після створення нового запису в базі даних. - * Особливий випадок – `204`, "No Content" (немає вмісту). Ця відповідь використовується, коли немає даних для повернення клієнту, тому відповідь не повинна мати тіла. -* **`300 - 399`** "Перенаправлення". Відповіді з цими кодами можуть мати або не мати тіла, за винятком `304`, "Not Modified" (не змінено), яка не повинна мати тіла. -* **`400 - 499`** "Помилка клієнта". Це другий тип, який Ви, ймовірно, будете використовувати найчастіше. - * Приклад `404`, "Not Found" (не знайдено). - * Для загальних помилок клієнта можна використовувати `400`. -* `500 - 599` "Помилки сервера". Ви майже ніколи не використовуєте їх напряму. Якщо в коді Вашого застосунку або на сервері щось пішло не так, автоматично буде повернено один із цих кодів статусу. +* `100 - 199` — для «Information». Ви рідко використовуєте їх напряму. Відповіді з такими кодами статусу не можуть мати тіла. +* **`200 - 299`** — для «Successful» відповідей. Це ті, які ви використовуватимете найчастіше. + * `200` — код статусу за замовчуванням, який означає, що все було «OK». + * Інший приклад — `201`, «Created». Його зазвичай використовують після створення нового запису в базі даних. + * Особливий випадок — `204`, «No Content». Цю відповідь використовують, коли немає вмісту для повернення клієнту, і тому відповідь не повинна мати тіла. +* **`300 - 399`** — для «Redirection». Відповіді з цими кодами статусу можуть мати або не мати тіла, за винятком `304`, «Not Modified», яка не повинна мати тіла. +* **`400 - 499`** — для відповідей «Client error». Це другий тип, який ви, ймовірно, будете використовувати найчастіше. + * Приклад — `404`, для відповіді «Not Found». + * Для загальних помилок з боку клієнта ви можете просто використовувати `400`. +* `500 - 599` — для помилок сервера. Ви майже ніколи не використовуєте їх напряму. Коли щось піде не так у якійсь частині коду вашого застосунку або на сервері, автоматично буде повернено один із цих кодів статусу. /// tip | Порада -Щоб дізнатися більше про кожен код статусу і призначення кожного з них, перегляньте документацію MDN про HTTP коди статусу. +Щоб дізнатися більше про кожен код статусу і для чого призначений кожен із них, перегляньте документацію MDN про HTTP коди статусу. /// -## Легкий спосіб запам'ятати назви +## Скорочення, щоб запам’ятати назви { #shortcut-to-remember-the-names } -Розглянемо ще раз попередній приклад: +Розглянемо попередній приклад ще раз: -{* ../../docs_src/response_status_code/tutorial001.py hl[6] *} +{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *} -`201` - це код статусу для "Created" (створено). +`201` — це код статусу для «Created». -Але Вам не потрібно запам'ятовувати, що означає кожен із цих кодів. +Але вам не потрібно запам'ятовувати, що означає кожен із цих кодів. -Ви можете використовувати зручні змінні з `fastapi.status` +Ви можете використовувати зручні змінні з `fastapi.status`. -{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *} +{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *} -Ці змінні просто для зручності. Вони містять ті ж самі числа, але Ви можете скористатися автозаповненням в редакторі: +Вони — просто для зручності, містять те саме число, але так ви можете скористатися автозаповненням редактора, щоб знайти їх: @@ -91,10 +92,10 @@ FastAPI знає про це і створить OpenAPI документаці Ви також можете використати `from starlette import status`. -**FastAPI** надає ті ж самі змінні `starlette.status` як `fastapi.status`, просто для зручності розробника. Однак вони походять безпосередньо зі Starlette. +**FastAPI** надає той самий `starlette.status` як `fastapi.status` просто як зручність для вас, розробника. Але він походить безпосередньо зі Starlette. /// -## Зміна значення за замовчуванням +## Зміна значення за замовчуванням { #changing-the-default } -Далі, у Посібнику для досвідчених користувачів{.internal-link target=_blank}, Ви дізнаєтесь, як повернути інший код статусу, ніж той, який Ви оголосили тут. +Пізніше, у [Посібнику для досвідчених користувачів](../advanced/response-change-status-code.md){.internal-link target=_blank}, ви побачите, як повертати інший код статусу, ніж значення за замовчуванням, яке ви оголошуєте тут. diff --git a/docs/uk/docs/tutorial/schema-extra-example.md b/docs/uk/docs/tutorial/schema-extra-example.md index 853fd5e659..54608c2ab1 100644 --- a/docs/uk/docs/tutorial/schema-extra-example.md +++ b/docs/uk/docs/tutorial/schema-extra-example.md @@ -1,44 +1,22 @@ -# Декларування прикладів вхідних даних +# Декларування прикладів вхідних даних { #declare-request-example-data } Ви можете задати приклади даних, які Ваш застосунок може отримувати. Ось кілька способів, як це зробити. -## Додаткові дані JSON-схеми в моделях Pydantic +## Додаткові дані JSON-схеми в моделях Pydantic { #extra-json-schema-data-in-pydantic-models } Ви можете задати `examples` для моделі Pydantic, які буде додано до згенерованої JSON-схеми. -//// tab | Pydantic v2 - {* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *} -//// - -//// tab | Pydantic v1 - -{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *} - -//// - -Ця додаткова інформація буде додана як є до **JSON-схеми**, і вона буде використовуватися в документації до API. - -//// tab | Pydantic v2 +Ця додаткова інформація буде додана як є до **JSON-схеми** для цієї моделі, і вона буде використана в документації до API. -У версії Pydantic 2 використовується атрибут `model_config`, який приймає `dict`, як описано в документації Pydantic: Конфігурація. +Ви можете використати атрибут `model_config`, який приймає `dict`, як описано в документації Pydantic: Configuration. Ви можете встановити `"json_schema_extra"` як `dict`, що містить будь-які додаткові дані, які Ви хочете відобразити у згенерованій JSON-схемі, включаючи `examples`. -//// - -//// tab | Pydantic v1 - -У версії Pydantic 1 використовується внутрішній клас `Config` і параметр `schema_extra`, як описано в документації Pydantic: Налаштування схеми. - -Ви можете задати `schema_extra` як `dict`, що містить будь-які додаткові дані, які Ви хочете бачити у згенерованій JSON-схемі, включаючи `examples`. - -//// - -/// tip | Підказка +/// tip | Порада Ви можете використати ту ж техніку, щоб розширити JSON-схему і додати власну додаткову інформацію. @@ -50,19 +28,19 @@ OpenAPI 3.1.0 (який використовується починаючи з FastAPI 0.99.0) додав підтримку `examples`, що є частиною стандарту **JSON-схеми**. -До цього підтримувався лише ключ `example` з одним прикладом. Він все ще підтримується в OpenAPI 3.1.0, але є застарілим і не входить до стандарту JSON Schema. Тому рекомендується перейти з `example` на `examples`. 🤓 +До цього підтримувався лише ключ `example` з одним прикладом. Він все ще підтримується в OpenAPI 3.1.0, але є застарілим і не входить до стандарту JSON Schema. Тому рекомендується перейти з `example` на `examples`. 🤓 Більше про це можна прочитати в кінці цієї сторінки. /// -## Додаткові аргументи `Field` +## Додаткові аргументи `Field` { #field-additional-arguments } Коли ви використовуєте `Field()` у моделях Pydantic, Ви також можете вказати додаткові `examples`: {* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *} -## `examples` у JSON-схемі — OpenAPI +## `examples` у JSON-схемі — OpenAPI { #examples-in-json-schema-openapi } При використанні будь-кого з наступного: @@ -76,41 +54,41 @@ OpenAPI 3.1.0 (який використовується починаючи з F Ви також можете задати набір `examples` з додатковою інформацією, яка буде додана до їхніх **JSON-схем** у **OpenAPI**. -### `Body` з `examples` +### `Body` з `examples` { #body-with-examples } Тут ми передаємо `examples`, які містять один приклад очікуваних даних у `Body()`: {* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *} -### Приклад у UI документації +### Приклад у UI документації { #example-in-the-docs-ui } -За допомогою будь-якого з наведених вище методів це виглядатиме так у документації за `/docs`: +За допомогою будь-якого з наведених вище методів це виглядатиме так у `/docs`: -### `Body` з кількома `examples` +### `Body` з кількома `examples` { #body-with-multiple-examples } Звичайно, Ви також можете передати кілька `examples`: {* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *} -Коли Ви це робите, приклади будуть частиною внутрішньої **JSON-схеми** для цих даних. +Коли Ви це робите, приклади будуть частиною внутрішньої **JSON-схеми** для цих даних тіла. -Втім, на момент написання цього (26 серпня 2023), Swagger UI — інструмент, який відповідає за відображення UI документації — не підтримує показ кількох прикладів у **JSON-схеми**. Але нижче можна прочитати про обхідний шлях. +Втім, на момент написання цього (час написання цього), Swagger UI — інструмент, який відповідає за відображення UI документації — не підтримує показ кількох прикладів для даних у **JSON-схемі**. Але нижче можна прочитати про обхідний шлях. -### Специфічні для OpenAPI `examples` +### Специфічні для OpenAPI `examples` { #openapi-specific-examples } -Ще до того, як **JSON-схема** почала підтримувати `examples`, OpenAPI вже мала підтримку поля з такою ж назвою — `examples`. +Ще до того, як **JSON-схема** почала підтримувати `examples`, OpenAPI вже мала підтримку іншого поля, яке також називається `examples`. -Це **специфічне для OpenAPI** поле `examples` розміщується в іншій частині специфікації OpenAPI — у **деталях кожної *операції шляху***, а не всередині самої JSON-схеми. +Це **специфічне для OpenAPI** поле `examples` розміщується в іншому розділі специфікації OpenAPI. Воно розміщується в **деталях кожної *операції шляху***, а не всередині кожної JSON-схеми. -Swagger UI вже давно підтримує це поле `examples`. Тому Ви можете використовувати його, щоб **відображати** кілька **прикладів у документації**. +І Swagger UI вже давно підтримує це поле `examples`. Тому Ви можете використовувати його, щоб **відображати** різні **приклади в UI документації**. -Це поле `examples` у специфікації OpenAPI — це `dict` (словник) з **кількома прикладами** (а не список `list`), кожен із яких може містити додаткову інформацію, що буде додана до **OpenAPI**. +Форма цього специфічного для OpenAPI поля `examples` — це `dict` з **кількома прикладами** (а не `list`), кожен із яких має додаткову інформацію, яка також буде додана до **OpenAPI**. -Воно не включається до JSON Schema кожного параметра, а розміщується зовні, безпосередньо в *операції шляху*. +Воно не включається всередину кожної JSON-схеми, що міститься в OpenAPI, воно розміщується зовні, безпосередньо в *операції шляху*. -### Використання параметра `openapi_examples` +### Використання параметра `openapi_examples` { #using-the-openapi-examples-parameter } Ви можете оголосити специфічні для OpenAPI `examples` у FastAPI за допомогою параметра `openapi_examples` для: @@ -122,30 +100,32 @@ Swagger UI вже давно підтримує це поле `examples`. Том * `Form()` * `File()` -Ключі словника (`dict`) ідентифікують кожен приклад, а кожне значення `dict` — кожен специфічний словник `dict` в `examples` може містити: +Ключі `dict` ідентифікують кожен приклад, а кожне значення — це інший `dict`. + +Кожен специфічний `dict` прикладу в `examples` може містити: * `summary`: короткий опис прикладу. -* `description`: розгорнутий опис (може містити Markdown). -* `value`: сам приклад, наприклад, словник (`dict`). -* `externalValue`: альтернатива `value`, URL-адреса, що вказує на приклад. Проте ця опція може не підтримуватися більшістю інструментів, на відміну від `value`. +* `description`: розгорнутий опис, який може містити Markdown. +* `value`: це сам приклад, який буде показано, наприклад `dict`. +* `externalValue`: альтернатива `value`, URL-адреса, що вказує на приклад. Проте це може не підтримуватися такою кількістю інструментів, як `value`. Використання виглядає так: {* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *} -### Приклади OpenAPI у UI документації +### Приклади OpenAPI в UI документації { #openapi-examples-in-the-docs-ui } -З параметром `openapi_examples`, доданим до `Body()`, документація `/docs` виглядатиме так: +З `openapi_examples`, доданим до `Body()`, `/docs` виглядатиме так: -## Технічні деталі +## Технічні деталі { #technical-details } -/// tip | Підказка +/// tip | Порада -Якщо Ви вже використовуєте **FastAPI** версії **0.99.0 або вище**, Ви можете **пропустити** цей розділ. +Якщо Ви вже використовуєте **FastAPI** версії **0.99.0 або вище**, Ви, ймовірно, можете **пропустити** ці технічні деталі. -Він більш актуальний для старих версій, до появи OpenAPI 3.1.0. +Вони більш актуальні для старих версій, до появи OpenAPI 3.1.0. Можна вважати це коротким **історичним екскурсом** у OpenAPI та JSON Schema. 🤓 @@ -155,68 +135,68 @@ Swagger UI вже давно підтримує це поле `examples`. Том Це дуже технічна інформація про стандарти **JSON Schema** і **OpenAPI**. -Якщо вищезгадані ідеї вже працюють у Вас — можете не заглиблюватися в ці деталі. +Якщо вищезгадані ідеї вже працюють у Вас, цього може бути достатньо, і Вам, ймовірно, не потрібні ці деталі — можете пропустити. /// -До OpenAPI 3.1.0 специфікація використовувала стару та модифіковану версію **JSON Schema**. +До OpenAPI 3.1.0 OpenAPI використовував стару та модифіковану версію **JSON Schema**. -Оскільки JSON Schema раніше не підтримувала `examples`, OpenAPI додала власне поле `examples`. +JSON Schema не мала `examples`, тож OpenAPI додала власне поле `example` до своєї модифікованої версії. -OpenAPI також додала `example` і `examples` до інших частин специфікації: +OpenAPI також додала поля `example` і `examples` до інших частин специфікації: -* `Parameter Object` (в специфікації) використовується FastAPI для: +* `Parameter Object` (в специфікації), який використовувався утилітами FastAPI: * `Path()` * `Query()` * `Header()` * `Cookie()` -* `Request Body Object`, в полі `content`, в `Media Type Object` (в специфікації) використовується FastAPI для: +* `Request Body Object`, у полі `content`, у `Media Type Object` (в специфікації), який використовувався утилітами FastAPI: * `Body()` * `File()` * `Form()` /// info | Інформація -Цей старий параметр `examples`, специфічний для OpenAPI, тепер називається `openapi_examples`, починаючи з FastAPI версії `0.103.0`. +Цей старий специфічний для OpenAPI параметр `examples` тепер називається `openapi_examples`, починаючи з FastAPI `0.103.0`. /// -### Поле `examples` у JSON Schema +### Поле `examples` у JSON Schema { #json-schemas-examples-field } Пізніше JSON Schema додала поле `examples` у нову версію специфікації. -І вже OpenAPI 3.1.0 базується на цій новій версії (JSON Schema 2020-12), яка включає поле `examples`. +А потім новий OpenAPI 3.1.0 базувався на найновішій версії (JSON Schema 2020-12), яка включала це нове поле `examples`. -Тепер це поле `examples` є пріоритетним і замінює старе (і кастомне) поле `example`, яке стало застарілим. +І тепер це нове поле `examples` має вищий пріоритет за старе одиночне (і кастомне) поле `example`, яке тепер є застарілим. -Нове поле `examples` у JSON Schema — це **просто список (`list`)** прикладів, без додаткових метаданих (на відміну від OpenAPI). +Це нове поле `examples` у JSON Schema — це **просто `list`** прикладів, а не `dict` з додатковими метаданими, як в інших місцях OpenAPI (описаних вище). /// info | Інформація -Навіть після того, як з'явився OpenAPI 3.1.0, який підтримував examples у JSON Schema, інструмент Swagger UI ще деякий час не підтримував цю версію (підтримка з’явилась з версії 5.0.0 🎉). +Навіть після релізу OpenAPI 3.1.0 з цією новою простішою інтеграцією з JSON Schema, протягом певного часу Swagger UI, інструмент, який надає автоматичну документацію, не підтримував OpenAPI 3.1.0 (тепер підтримує, починаючи з версії 5.0.0 🎉). Через це версії FastAPI до 0.99.0 все ще використовували версії OpenAPI нижчі за 3.1.0. /// -### `Examples` в Pydantic і FastAPI +### `examples` у Pydantic і FastAPI { #pydantic-and-fastapi-examples } -Коли Ви додаєте `examples` у модель Pydantic через `schema_extra` або `Field(examples=["something"])`, ці приклади додаються до **JSON Schema** цієї моделі. +Коли Ви додаєте `examples` у модель Pydantic через `schema_extra` або `Field(examples=["something"])`, цей приклад додається до **JSON Schema** для цієї моделі Pydantic. -І ця **JSON Schema** Pydantic-моделі включається до **OpenAPI** Вашого API, а потім використовується в UI документації (docs UI). +І ця **JSON Schema** Pydantic-моделі включається до **OpenAPI** Вашого API, а потім використовується в UI документації. -У версіях FastAPI до 0.99.0 (починаючи з 0.99.0 використовується новіший OpenAPI 3.1.0), коли Ви використовували `example` або `examples` з іншими утилітами (`Query()`, `Body()` тощо), ці приклади не додавалися до JSON Schema, який описує ці дані (навіть не до власної версії JSON Schema у OpenAPI). Натомість вони додавалися безпосередньо до опису *обробника шляху* *(path operation)* в OpenAPI (тобто поза межами частин, які використовують JSON Schema). +У версіях FastAPI до 0.99.0 (0.99.0 і вище використовують новіший OpenAPI 3.1.0), коли Ви використовували `example` або `examples` з будь-якими іншими утилітами (`Query()`, `Body()` тощо), ці приклади не додавалися до JSON Schema, що описує ці дані (навіть не до власної версії JSON Schema в OpenAPI), натомість вони додавалися безпосередньо до декларації *операції шляху* в OpenAPI (поза межами частин OpenAPI, які використовують JSON Schema). -Але тепер, коли FastAPI 0.99.0 і вище використовують OpenAPI 3.1.0, а той — JSON Schema 2020-12, разом із Swagger UI 5.0.0 і вище — все стало більш узгодженим, і examples тепер включаються до JSON Schema. +Але тепер, коли FastAPI 0.99.0 і вище використовує OpenAPI 3.1.0, який використовує JSON Schema 2020-12, і Swagger UI 5.0.0 і вище, все стало більш узгодженим, і приклади включаються до JSON Schema. -### Swagger UI та специфічні для OpenAPI `examples` +### Swagger UI та специфічні для OpenAPI `examples` { #swagger-ui-and-openapi-specific-examples } -Раніше (станом на 26 серпня 2023 року) Swagger UI не підтримував кілька прикладів у JSON Schema, тому користувачі не мали можливості показати декілька прикладів у документації. +Оскільки Swagger UI не підтримував кілька прикладів JSON Schema (станом на 2023-08-26), користувачі не мали можливості показати кілька прикладів у документації. -Щоб вирішити це, FastAPI починаючи з версії 0.103.0 **додав підтримку** старого **OpenAPI-специфічного** поля `examples` через новий параметр `openapi_examples`. 🤓 +Щоб вирішити це, FastAPI `0.103.0` **додав підтримку** оголошення того самого старого **OpenAPI-специфічного** поля `examples` через новий параметр `openapi_examples`. 🤓 -### Підсумок +### Підсумок { #summary } -Раніше я казав, що не люблю історію... а тепер ось я — розповідаю "технічні історичні" лекції. 😅 +Раніше я казав, що не дуже люблю історію... а тепер подивіться на мене — читаю «технічні історичні» лекції. 😅 Коротко: **оновіться до FastAPI 0.99.0 або вище** — і все стане значно **простішим, узгодженим та інтуїтивно зрозумілим**, і Вам не доведеться знати всі ці історичні деталі. 😎 diff --git a/docs/uk/docs/tutorial/security/index.md b/docs/uk/docs/tutorial/security/index.md index c3d94be8d9..f1fb25178d 100644 --- a/docs/uk/docs/tutorial/security/index.md +++ b/docs/uk/docs/tutorial/security/index.md @@ -1,70 +1,72 @@ -# Безпека +# Безпека { #security } Існує багато способів реалізувати безпеку, автентифікацію та авторизацію. -Це зазвичай складна і "непроста" тема. +І зазвичай це складна і «непроста» тема. -У багатьох фреймворках і системах забезпечення безпеки та автентифікації займає величезну частину зусиль і коду (іноді — понад 50% всього написаного коду). +У багатьох фреймворках і системах лише обробка безпеки та автентифікації потребує великих зусиль і коду (у багатьох випадках це може бути 50% або більше від усього написаного коду). -**FastAPI** надає кілька інструментів, які допоможуть Вам впоратися з **безпекою** легко, швидко, стандартним способом, без необхідності вивчати всі специфікації безпеки. +**FastAPI** надає кілька інструментів, які допоможуть вам працювати з **безпекою** легко, швидко, стандартним способом, без необхідності вивчати всі специфікації безпеки. -Але спочатку — кілька коротких понять. +Але спочатку розгляньмо кілька невеликих понять. -## Поспішаєте? +## Поспішаєте? { #in-a-hurry } -Якщо Вам не цікаві всі ці терміни й просто потрібно *швидко* додати автентифікацію за логіном і паролем — переходьте до наступних розділів. +Якщо вам не цікаві всі ці терміни й вам просто потрібно додати безпеку з автентифікацією на основі імені користувача та пароля *прямо зараз*, переходьте до наступних розділів. -## OAuth2 +## OAuth2 { #oauth2 } -OAuth2 — це специфікація, що описує кілька способів обробки автентифікації та авторизації. +OAuth2 — це специфікація, що визначає кілька способів обробки автентифікації та авторизації. -Це досить об'ємна специфікація, яка охоплює складні випадки використання. +Це досить об'ємна специфікація, яка охоплює кілька складних випадків використання. -Вона включає способи автентифікації через "третю сторону". +Вона включає способи автентифікації через «третю сторону». -Саме це лежить в основі "входу через Google, Facebook, X (Twitter), GitHub" тощо. +Саме це лежить в основі всіх систем із «увійти через Facebook, Google, X (Twitter), GitHub». -### OAuth 1 +### OAuth 1 { #oauth-1 } -Раніше існував OAuth 1, який значно відрізняється від OAuth2 і є складнішим, оскільки містив специфікації для шифрування комунікацій. +Раніше існував OAuth 1, який значно відрізняється від OAuth2 і є складнішим, оскільки містив прямі специфікації щодо того, як шифрувати комунікацію. -Зараз майже не використовується. +Зараз він не дуже популярний або використовується. -OAuth2 не вказує, як саме шифрувати з'єднання — воно очікує, що ваш застосунок працює через HTTPS. +OAuth2 не вказує, як саме шифрувати комунікацію — він очікує, що ваш застосунок доступний через HTTPS. /// tip | Порада -У розділі про **деплой** Ви побачите, як налаштувати HTTPS безкоштовно з Traefik та Let's Encrypt. +У розділі про **деплой** ви побачите, як налаштувати HTTPS безкоштовно з Traefik та Let's Encrypt. /// -## OpenID Connect +## OpenID Connect { #openid-connect } OpenID Connect — ще одна специфікація, побудована на основі **OAuth2**. -Вона розширює OAuth2, уточнюючи деякі неоднозначності для досягнення кращої сумісності. +Вона просто розширює OAuth2, уточнюючи деякі відносно неоднозначні речі в OAuth2, щоб зробити його більш сумісним. -Наприклад, вхід через Google використовує OpenID Connect (який базується на OAuth2). +Наприклад, вхід через Google використовує OpenID Connect (який під капотом використовує OAuth2). -Але вхід через Facebook — ні. Він має власну реалізацію на базі OAuth2. +Але вхід через Facebook не підтримує OpenID Connect. Він має власний різновид OAuth2. -### OpenID (не "OpenID Connect") +### OpenID (не «OpenID Connect») { #openid-not-openid-connect } -Існувала також специфікація "OpenID", яка намагалася розвʼязати ті самі задачі, що й **OpenID Connect**, але не базувалась на OAuth2. +Існувала також специфікація «OpenID». Вона намагалася розвʼязати те саме, що й **OpenID Connect**, але не базувалась на OAuth2. -Це була зовсім інша система, і сьогодні вона майже не використовується. +Тож це була повністю додаткова система. -## OpenAPI +Зараз вона не дуже популярна або використовується. -OpenAPI (раніше Swagger) — це специфікація для побудови API (тепер під егідою Linux Foundation). +## OpenAPI { #openapi } + +OpenAPI (раніше відомий як Swagger) — це відкрита специфікація для побудови API (тепер частина Linux Foundation). **FastAPI** базується на **OpenAPI**. -Завдяки цьому Ви отримуєте автоматичну інтерактивну документацію, генерацію коду та багато іншого. +Саме це робить можливими кілька автоматичних інтерактивних інтерфейсів документації, генерацію коду тощо. -OpenAPI дозволяє описувати різні "схеми" безпеки. +OpenAPI має спосіб визначати різні «схеми» безпеки. -Використовуючи їх, Ви можете скористатися всіма цими інструментами, що базуються на стандартах, зокрема інтерактивними системами документації. +Використовуючи їх, ви можете скористатися всіма цими інструментами, що базуються на стандартах, зокрема цими інтерактивними системами документації. OpenAPI визначає такі схеми безпеки: @@ -72,33 +74,33 @@ OpenAPI визначає такі схеми безпеки: * Параметр запиту. * Заголовок. * Cookie. -* `http`: стандартні методи HTTP-автентифікації, включаючи: - * `bearer`: заголовок `Authorization` зі значенням `Bearer` та токеном. Це успадковано з OAuth2. - * HTTP Basic автентифікація - * HTTP Digest, тощо. +* `http`: стандартні системи HTTP-автентифікації, включаючи: + * `bearer`: заголовок `Authorization` зі значенням `Bearer ` та токеном. Це успадковано з OAuth2. + * HTTP Basic автентифікацію. + * HTTP Digest тощо. * `oauth2`: усі способи обробки безпеки за допомогою OAuth2 (так звані «потоки»). - * Деякі з цих потоків підходять для створення власного провайдера автентифікації OAuth 2.0 (наприклад, Google, Facebook, X (Twitter), GitHub тощо): - * `implicit`— неявний - * `clientCredentials`— облікові дані клієнта - * `authorizationCode` — код авторизації - * Але є один окремий «потік», який ідеально підходить для реалізації автентифікації всередині одного додатку: - * `password`: у наступних розділах буде приклад використання цього потоку. -* `openIdConnect`: дозволяє автоматично виявляти параметри автентифікації OAuth2. - * Це автоматичне виявлення визначається у специфікації OpenID Connect. + * Декілька з цих потоків підходять для створення провайдера автентифікації OAuth 2.0 (наприклад, Google, Facebook, X (Twitter), GitHub тощо): + * `implicit` + * `clientCredentials` + * `authorizationCode` + * Але є один окремий «потік», який можна ідеально використати для обробки автентифікації напряму в цьому ж застосунку: + * `password`: у кількох наступних розділах будуть приклади цього. +* `openIdConnect`: має спосіб визначити, як автоматично виявляти дані автентифікації OAuth2. + * Саме це автоматичне виявлення визначено у специфікації OpenID Connect. /// tip | Порада -Інтеграція інших провайдерів автентифікації/авторизації, таких як Google, Facebook, X (Twitter), GitHub тощо — також можлива і відносно проста. +Інтеграція інших провайдерів автентифікації/авторизації, таких як Google, Facebook, X (Twitter), GitHub тощо, також можлива і відносно проста. -Найскладніше — це створити власного провайдера автентифікації/авторизації, як Google чи Facebook. Але **FastAPI** надає Вам інструменти, щоб зробити це легко, беручи на себе важку частину роботи. +Найскладніше — це створити провайдера автентифікації/авторизації на кшталт таких, але **FastAPI** надає вам інструменти, щоб зробити це легко, виконуючи важку частину роботи за вас. /// -## Інструменти **FastAPI** +## Утиліти **FastAPI** { #fastapi-utilities } -FastAPI надає кілька інструментів для кожної з описаних схем безпеки в модулі `fastapi.security`, які спрощують використання цих механізмів захисту. +FastAPI надає кілька інструментів для кожної з описаних схем безпеки в модулі `fastapi.security`, які спрощують використання цих механізмів безпеки. -У наступних розділах Ви побачите, як додати безпеку до свого API за допомогою цих інструментів **FastAPI**. +У наступних розділах ви побачите, як додати безпеку до свого API за допомогою цих інструментів, які надає **FastAPI**. -А також побачите, як вона автоматично інтегрується в інтерактивну документацію вашого API. +А також побачите, як це автоматично інтегрується в інтерактивну систему документації. diff --git a/docs/uk/docs/tutorial/static-files.md b/docs/uk/docs/tutorial/static-files.md index 3427f23765..32ca1311d2 100644 --- a/docs/uk/docs/tutorial/static-files.md +++ b/docs/uk/docs/tutorial/static-files.md @@ -1,13 +1,13 @@ -# Статичні файли +# Статичні файли { #static-files } Ви можете автоматично надавати статичні файли з каталогу, використовуючи `StaticFiles`. -## Використання `StaticFiles` +## Використання `StaticFiles` { #use-staticfiles } * Імпортуйте `StaticFiles`. -* "Під'єднати" екземпляр `StaticFiles()` з вказанням необхідного шляху. +* «Під'єднати» екземпляр `StaticFiles()` з вказанням необхідного шляху. -{* ../../docs_src/static_files/tutorial001.py hl[2,6] *} +{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *} /// note | Технічні деталі @@ -17,24 +17,24 @@ /// -### Що таке "Під'єднання" +### Що таке «Під'єднання» { #what-is-mounting } -"Під'єднання" означає додавання повноцінного "незалежного" застосунку за певним шляхом, який потім обробляє всі під шляхи. +«Під'єднання» означає додавання повноцінного «незалежного» застосунку за певним шляхом, який потім обробляє всі під шляхи. -Це відрізняється від використання `APIRouter`, оскільки під'єднаний застосунок є повністю незалежним. OpenAPI та документація вашого основного застосунку не будуть знати нічого про ваш під'єднаний застосунок. +Це відрізняється від використання `APIRouter`, оскільки під'єднаний застосунок є повністю незалежним. OpenAPI та документація вашого основного застосунку не будуть знати нічого про ваш під'єднаний застосунок тощо. Ви можете дізнатися більше про це в [Посібнику для просунутих користувачів](../advanced/index.md){.internal-link target=_blank}. -## Деталі +## Деталі { #details } -Перше `"/static"` вказує на під шлях, за яким буде "під'єднано" цей новий "застосунок". Тому будь-який шлях, який починається з `"/static"`, буде оброблятися ним. +Перше `"/static"` вказує на під шлях, за яким буде «під'єднано» цей новий «підзастосунок». Тому будь-який шлях, який починається з `"/static"`, буде оброблятися ним. -`directory="static"` визначає каталог, що містить ваші статичні файли. +`directory="static"` визначає назву каталогу, що містить ваші статичні файли. `name="static"` це ім'я, яке можна використовувати всередині **FastAPI**. -Усі ці параметри можуть бути змінені відповідно до потреб і особливостей вашого застосунку. +Усі ці параметри можуть бути іншими за "`static`", налаштуйте їх відповідно до потреб і особливостей вашого застосунку. -## Додаткова інформація +## Додаткова інформація { #more-info } Детальніше про налаштування та можливості можна дізнатися в документації Starlette про статичні файли. diff --git a/docs/uk/docs/tutorial/testing.md b/docs/uk/docs/tutorial/testing.md index 1105c6b0a8..462592829f 100644 --- a/docs/uk/docs/tutorial/testing.md +++ b/docs/uk/docs/tutorial/testing.md @@ -1,17 +1,18 @@ -# Тестування +# Тестування { #testing } -Тестування **FastAPI** додатків є простим та ефективним завдяки бібліотеці Starlette, яка базується на HTTPX. -Оскільки HTTPX розроблений на основі Requests, його API є інтуїтивно зрозумілим для тих, хто вже знайомий з Requests. +Завдяки Starlette тестувати застосунки **FastAPI** просто й приємно. -З його допомогою Ви можете використовувати pytest безпосередньо з **FastAPI**. +Воно базується на HTTPX, який, своєю чергою, спроєктований на основі Requests, тож він дуже знайомий та інтуїтивно зрозумілий. -## Використання `TestClient` +З його допомогою ви можете використовувати pytest безпосередньо з **FastAPI**. + +## Використання `TestClient` { #using-testclient } /// info | Інформація Щоб використовувати `TestClient`, спочатку встановіть `httpx`. -Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили саму бібліотеку, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили `httpx`, наприклад: ```console $ pip install httpx @@ -21,7 +22,7 @@ $ pip install httpx Імпортуйте `TestClient`. -Створіть `TestClient`, передавши йому Ваш застосунок **FastAPI**. +Створіть `TestClient`, передавши йому ваш застосунок **FastAPI**. Створюйте функції з іменами, що починаються з `test_` (це стандартна угода для `pytest`). @@ -29,8 +30,7 @@ $ pip install httpx Записуйте прості `assert`-вирази зі стандартними виразами Python, які потрібно перевірити (це також стандарт для `pytest`). -{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *} - +{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *} /// tip | Порада @@ -46,25 +46,25 @@ $ pip install httpx Ви також можете використовувати `from starlette.testclient import TestClient`. -**FastAPI** надає той самий `starlette.testclient` під назвою `fastapi.testclient` для зручності розробників, але він безпосередньо походить із Starlette. +**FastAPI** надає той самий `starlette.testclient` під назвою `fastapi.testclient` просто для зручності для вас, розробника. Але він безпосередньо походить із Starlette. /// /// tip | Порада -Якщо Вам потрібно викликати `async`-функції у ваших тестах, окрім відправлення запитів до FastAPI-застосунку (наприклад, асинхронні функції роботи з базою даних), перегляньте [Асинхронні тести](../advanced/async-tests.md){.internal-link target=_blank} у розширеному керівництві. +Якщо ви хочете викликати `async`-функції у ваших тестах, окрім відправлення запитів до вашого застосунку FastAPI (наприклад, асинхронні функції роботи з базою даних), перегляньте [Async Tests](../advanced/async-tests.md){.internal-link target=_blank} у розширеному керівництві. /// -## Розділення тестів +## Розділення тестів { #separating-tests } -У реальному застосунку Ваші тести, ймовірно, будуть в окремому файлі. +У реальному застосунку ваші тести, ймовірно, будуть в окремому файлі. -Також Ваш **FastAPI**-застосунок може складатися з кількох файлів або модулів тощо. +Також ваш застосунок **FastAPI** може складатися з кількох файлів/модулів тощо. -### Файл застосунку **FastAPI** +### Файл застосунку **FastAPI** { #fastapi-app-file } -Припустимо, у Вас є структура файлів, описана в розділі [Більші застосунки](bigger-applications.md){.internal-link target=_blank}: +Припустимо, у вас є структура файлів, описана в розділі [Bigger Applications](bigger-applications.md){.internal-link target=_blank}: ``` . @@ -72,14 +72,15 @@ $ pip install httpx │   ├── __init__.py │   └── main.py ``` -У файлі `main.py` знаходиться Ваш застосунок **FastAPI** : -{* ../../docs_src/app_testing/main.py *} +У файлі `main.py` знаходиться ваш застосунок **FastAPI**: -### Файл тестування -Ви можете створити файл `test_main.py` з Вашими тестами. Він може знаходитися в тому ж пакеті Python (у тій самій директорії з файлом `__init__.py`): +{* ../../docs_src/app_testing/app_a_py39/main.py *} +### Файл тестування { #testing-file } + +Ви можете створити файл `test_main.py` з вашими тестами. Він може знаходитися в тому ж пакеті Python (у тій самій директорії з файлом `__init__.py`): ``` hl_lines="5" . @@ -89,18 +90,18 @@ $ pip install httpx │   └── test_main.py ``` -Оскільки цей файл знаходиться в тому ж пакеті, Ви можете використовувати відносний імпорт, щоб імпортувати об'єкт `app` із модуля `main` (`main.py`): +Оскільки цей файл знаходиться в тому ж пакеті, ви можете використовувати відносний імпорт, щоб імпортувати об'єкт `app` із модуля `main` (`main.py`): -{* ../../docs_src/app_testing/test_main.py hl[3] *} +{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *} ...і написати код для тестів так само як і раніше. -## Тестування: розширений приклад +## Тестування: розширений приклад { #testing-extended-example } Тепер розширимо цей приклад і додамо більше деталей, щоб побачити, як тестувати різні частини. -### Розширений файл застосунку **FastAPI** +### Розширений файл застосунку **FastAPI** { #extended-fastapi-app-file } Залишимо ту саму структуру файлів: @@ -112,75 +113,26 @@ $ pip install httpx │   └── test_main.py ``` -Припустимо, що тепер файл `main.py` із Вашим **FastAPI**-застосунком містить додаткові операції шляху (**path operations**). +Припустимо, що тепер файл `main.py` із вашим застосунком **FastAPI** містить інші **операції шляху**. Він має `GET`-операцію, яка може повертати помилку. Він має `POST`-операцію, яка може повертати кілька помилок. -Обидві операції шляху вимагають заголовок `X-Token`. - -//// tab | Python 3.10+ - -```Python -{!> ../../docs_src/app_testing/app_b_an_py310/main.py!} -``` - -//// - -//// tab | Python 3.9+ - -```Python -{!> ../../docs_src/app_testing/app_b_an_py39/main.py!} -``` - -//// - -//// tab | Python 3.8+ - -```Python -{!> ../../docs_src/app_testing/app_b_an/main.py!} -``` - -//// - -//// tab | Python 3.10+ non-Annotated +Обидві *операції шляху* вимагають заголовок `X-Token`. -/// tip | Порада - -Бажано використовувати версію з `Annotated`, якщо це можливо - -/// - -```Python -{!> ../../docs_src/app_testing/app_b_py310/main.py!} -``` - -//// - -//// tab | Python 3.8+ non-Annotated +{* ../../docs_src/app_testing/app_b_an_py310/main.py *} -/// tip | Порада - -Бажано використовувати версію з `Annotated`, якщо це можливо - -/// +### Розширений тестовий файл { #extended-testing-file } -```Python -{!> ../../docs_src/app_testing/app_b/main.py!} -``` - -//// +Потім ви можете оновити `test_main.py`, додавши розширені тести: -### Розширений тестовий файл +{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *} -Потім Ви можете оновити `test_main.py`, додавши розширені тести: -{* ../../docs_src/app_testing/app_b/test_main.py *} +Коли вам потрібно передати клієнту інформацію в запиті, але ви не знаєте, як це зробити, ви можете пошукати (Google), як це зробити в `httpx`, або навіть як це зробити з `requests`, оскільки дизайн HTTPX базується на дизайні Requests. -Коли Вам потрібно передати клієнту інформацію в запиті, але Ви не знаєте, як це зробити, Ви можете пошукати (наприклад, у Google) спосіб реалізації в `httpx`, або навіть у `requests`, оскільки HTTPX розроблений на основі дизайну Requests. - -Далі Ви просто повторюєте ці ж дії у ваших тестах. +Далі ви просто повторюєте ці ж дії у ваших тестах. Наприклад: @@ -195,15 +147,16 @@ $ pip install httpx /// info | Інформація Зверніть увагу, що `TestClient` отримує дані, які можна конвертувати в JSON, а не Pydantic-моделі. -Якщо у Вас є Pydantic-модель у тесті, і Ви хочете передати її дані в додаток під час тестування, Ви можете використати `jsonable_encoder`, описаний у розділі [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}. + +Якщо у вас є Pydantic-модель у тесті, і ви хочете передати її дані в застосунок під час тестування, ви можете використати `jsonable_encoder`, описаний у розділі [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}. /// -## Запуск тестів +## Запуск { #run-it } Після цього вам потрібно встановити `pytest`. -Переконайтеся, що Ви створили [віртуальне середовище]{.internal-link target=_blank}, активували його і встановили необхідні пакети, наприклад: +Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його і встановили необхідні пакети, наприклад:
@@ -215,7 +168,7 @@ $ pip install pytest
-`pytest` автоматично знайде файли з тестами, виконає їх і надасть вам результати. +Він автоматично знайде файли та тести, виконає їх і повідомить вам результати. Запустіть тести за допомогою: diff --git a/scripts/docs.py b/scripts/docs.py index 84cf01c724..a9abce56b5 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -25,6 +25,7 @@ SUPPORTED_LANGS = { "es", "pt", "ru", + "uk", }