From b61e42c664158539b19acc466d0598baa437548d Mon Sep 17 00:00:00 2001 From: Aleksandr Date: Tue, 26 Sep 2023 21:30:55 +0300 Subject: [PATCH 1/3] Upload files Russian translate --- docs/ru/docs/tutorial/request-files.md | 314 +++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 docs/ru/docs/tutorial/request-files.md diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md new file mode 100644 index 0000000000000..2adaf69b6cb51 --- /dev/null +++ b/docs/ru/docs/tutorial/request-files.md @@ -0,0 +1,314 @@ +# Загрузка файлов + +С помощью `File` можно определить файлы, которые клиент будет загружать. + +!!! info "Дополнительная информация" + Чтобы получать загруженные файлы, сначала установите `python-multipart`. + + Например: `pip install python-multipart`. + + Это связано с тем, что загружаемые файлы передаются как данные формы. + +## Импорт `File` + +Импортируйте `File` и `UploadFile` из модуля `fastapi`: + +=== "Python 3.9+" + + ```Python hl_lines="3" + {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="1" + {!> ../../../docs_src/request_files/tutorial001_an.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="1" + {!> ../../../docs_src/request_files/tutorial001.py!} + ``` + +## Определите параметры `File` + +Создавайте параметры `File` так же, как вы это делаете для `Body` или `Form`: + +=== "Python 3.9+" + + ```Python hl_lines="9" + {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="8" + {!> ../../../docs_src/request_files/tutorial001_an.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="7" + {!> ../../../docs_src/request_files/tutorial001.py!} + ``` + +!!! info "Дополнительная информация" + `File` - это класс, который наследуется непосредственно от `Form`. + + Но помните, что когда вы импортируете `Query`, `Path`, `File` и другие из `fastapi`, на самом деле это функции, которые возвращают специальные классы. + +!!! tip "Подсказка" + Для объявления тела файла необходимо использовать `File`, поскольку в противном случае параметры будут интерпретироваться как параметры запроса или параметры тела (JSON). + +Файлы будут загружены как данные формы. + +Если вы объявите тип параметра у *функции операции пути* как `bytes`, то **FastAPI** прочитает файл за вас, и вы получите его содержимое в виде `bytes`. + +Следует иметь в виду, что это означает, что все содержимое будет храниться в памяти. Это хорошо подходит для небольших файлов. + +Однако есть несколько случаев, когда использование `UploadFile` может оказаться полезным. + +## Загрузка файла с помощью `UploadFile` + +Определите параметр файла с типом `UploadFile`: + +=== "Python 3.9+" + + ```Python hl_lines="14" + {!> ../../../docs_src/request_files/tutorial001_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="13" + {!> ../../../docs_src/request_files/tutorial001_an.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="12" + {!> ../../../docs_src/request_files/tutorial001.py!} + ``` + +Использование `UploadFile` имеет ряд преимуществ перед `bytes`: + +* Использовать `File()` в значении параметра по умолчанию не обязательно. +* При этом используется "буферный" файл: + * Файл, хранящийся в памяти до максимального предела размера, после преодоления которого он будет храниться на диске. +* Это означает, что он будет хорошо работать с большими файлами, такими как изображения, видео, большие бинарные файлы и т.д., не потребляя при этом всю память. +* Из загруженного файла можно получить метаданные. +* Он реализует file-like `async` интерфейс. +* Он предоставляет реальный объект Python `SpooledTemporaryFile` который вы можете передать непосредственно другим библиотекам, которые ожидают файл в качестве объекта. + +### `UploadFile` + +`UploadFile` имеет следующие атрибуты: + +* `filename`: Строка `str` с исходным именем файла, который был загружен (например, `myimage.jpg`). +* `content_type`: Строка `str` с типом содержимого (MIME type / media type) (например, `image/jpeg`). +* `file`: `SpooledTemporaryFile` (a file-like объект). Это фактический файл Python, который можно передавать непосредственно другим функциям или библиотекам, ожидающим файл в качестве объекта. + +`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний SpooledTemporaryFile). + +* `write(data)`: Записать данные `data` (`str` или `bytes`) в файл. +* `read(size)`: Прочитать количество `size` (`int`) байт/символов из файла. +* `seek(offset)`: Перейти к байту на позиции `offset` (`int`) в файле. + * Наример, `await myfile.seek(0)` перейдет к началу файла. + * Это особенно удобно, если вы один раз выполнили команду `await myfile.read()`, а затем вам нужно прочитать содержимое файла еще раз. +* `close()`: Закрыть файл. + +Поскольку все эти методы являются `async` методами, вам следует использовать "await" вместе с ними. + +Например, внутри `async` *функции операции пути* можно получить содержимое с помощью: + +```Python +contents = await myfile.read() +``` + +Если вы находитесь внутри обычной `def` *функции операции пути*, можно получить прямой доступ к файлу `UploadFile.file`, например: + +```Python +contents = myfile.file.read() +``` + +!!! note "Технические детали `async`" + При использовании методов `async` **FastAPI** запускает файловые методы в пуле потоков и ожидает их. + +!!! note "Технические детали Starlette" + **FastAPI** наследует `UploadFile` непосредственно из **Starlette**, но добавляет некоторые детали для совместимости с **Pydantic** и другими частями FastAPI. + +## Про "Form Data" + +Способ, которым HTML-формы (`
`) отправляют данные на сервер, обычно использует "специальную" кодировку для этих данных, отличную от JSON. + +**FastAPI** позаботится о том, чтобы считать эти данные из нужного места, а не из JSON. + +!!! note "Технические детали" + Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы. + + Но когда форма включает файлы, она кодируется как multipart/form-data. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела. + + Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке MDN web docs for POST. + +!!! warning "Внимание" + В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`. + + Это не является ограничением **FastAPI**, это часть протокола HTTP. + +## Необяхательная загрузка файлов + +Вы можете сделать загрузку файла необязательной, используя стандартные аннотации типов и установив значение по умолчанию `None`: + +=== "Python 3.10+" + + ```Python hl_lines="9 17" + {!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!} + ``` + +=== "Python 3.9+" + + ```Python hl_lines="9 17" + {!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="10 18" + {!> ../../../docs_src/request_files/tutorial001_02_an.py!} + ``` + +=== "Python 3.10+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="7 15" + {!> ../../../docs_src/request_files/tutorial001_02_py310.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="9 17" + {!> ../../../docs_src/request_files/tutorial001_02.py!} + ``` + +## `UploadFile` с дополнительными метаданными + +Вы также можете использовать `File()` вместе с `UploadFile`, например, для установки дополнительных метаданных: + +=== "Python 3.9+" + + ```Python hl_lines="9 15" + {!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="8 14" + {!> ../../../docs_src/request_files/tutorial001_03_an.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="7 13" + {!> ../../../docs_src/request_files/tutorial001_03.py!} + ``` + +## Загрузка нескольких файлов + +Можно одновременно загружать несколько файлов. + +Они будут связаны с одним и тем же "полем формы", отправляемым с помощью данных формы. + +Для этого необходимо объявить список `bytes` или `UploadFile`: + +=== "Python 3.9+" + + ```Python hl_lines="10 15" + {!> ../../../docs_src/request_files/tutorial002_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="11 16" + {!> ../../../docs_src/request_files/tutorial002_an.py!} + ``` + +=== "Python 3.9+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="8 13" + {!> ../../../docs_src/request_files/tutorial002_py39.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="10 15" + {!> ../../../docs_src/request_files/tutorial002.py!} + ``` + +Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`. + +!!! note "Technical Details" + Можно также использовать `from starlette.responses import HTMLResponse`. + + **FastAPI** предоставляет те же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. + +### Загрузка нескольких файлов с дополнительными метаданными + +Так же, как и раньше, вы можете использовать `File()` для задания дополнительных параметров, даже для `UploadFile`: + +=== "Python 3.9+" + + ```Python hl_lines="11 18-20" + {!> ../../../docs_src/request_files/tutorial003_an_py39.py!} + ``` + +=== "Python 3.6+" + + ```Python hl_lines="12 19-21" + {!> ../../../docs_src/request_files/tutorial003_an.py!} + ``` + +=== "Python 3.9+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="9 16" + {!> ../../../docs_src/request_files/tutorial003_py39.py!} + ``` + +=== "Python 3.6+ без Annotated" + + !!! tip "Подсказка" + Предпочтительнее использовать версию с аннотацией, если это возможно. + + ```Python hl_lines="11 18" + {!> ../../../docs_src/request_files/tutorial003.py!} + ``` + +## Резюме + +Используйте `File`, `bytes` и `UploadFile` для объявления файлов, которые будут загружаться и передаваться в виде данных формы. From f6963341927c35990109072daafed1019ef820a0 Mon Sep 17 00:00:00 2001 From: Aleksandr Andrukhov Date: Thu, 28 Sep 2023 22:16:00 +0300 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Vladislav Kramorenko <85196001+Xewus@users.noreply.github.com> --- docs/ru/docs/tutorial/request-files.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md index 2adaf69b6cb51..6055fdbb33cdf 100644 --- a/docs/ru/docs/tutorial/request-files.md +++ b/docs/ru/docs/tutorial/request-files.md @@ -1,6 +1,6 @@ # Загрузка файлов -С помощью `File` можно определить файлы, которые клиент будет загружать. +Используя класс `File`, мы можем позволить клиентам загружать файлы. !!! info "Дополнительная информация" Чтобы получать загруженные файлы, сначала установите `python-multipart`. @@ -36,7 +36,7 @@ ## Определите параметры `File` -Создавайте параметры `File` так же, как вы это делаете для `Body` или `Form`: +Создайте параметры `File` так же, как вы это делаете для `Body` или `Form`: === "Python 3.9+" @@ -71,9 +71,9 @@ Если вы объявите тип параметра у *функции операции пути* как `bytes`, то **FastAPI** прочитает файл за вас, и вы получите его содержимое в виде `bytes`. -Следует иметь в виду, что это означает, что все содержимое будет храниться в памяти. Это хорошо подходит для небольших файлов. +Следует иметь в виду, что все содержимое будет храниться в памяти. Это хорошо подходит для небольших файлов. -Однако есть несколько случаев, когда использование `UploadFile` может оказаться полезным. +Однако возможны случаи, когда использование `UploadFile` может оказаться полезным. ## Загрузка файла с помощью `UploadFile` @@ -165,7 +165,7 @@ contents = myfile.file.read() Это не является ограничением **FastAPI**, это часть протокола HTTP. -## Необяхательная загрузка файлов +## Необязательная загрузка файлов Вы можете сделать загрузку файла необязательной, используя стандартные аннотации типов и установив значение по умолчанию `None`: @@ -273,7 +273,7 @@ contents = myfile.file.read() !!! note "Technical Details" Можно также использовать `from starlette.responses import HTMLResponse`. - **FastAPI** предоставляет те же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. + **FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. ### Загрузка нескольких файлов с дополнительными метаданными @@ -311,4 +311,4 @@ contents = myfile.file.read() ## Резюме -Используйте `File`, `bytes` и `UploadFile` для объявления файлов, которые будут загружаться и передаваться в виде данных формы. +Используйте `File`, `bytes` и `UploadFile` для работы с файлами, которые будут загружаться и передаваться в виде данных формы. From e7a97c3037fc5860cb1461dedc3b90a0234714c0 Mon Sep 17 00:00:00 2001 From: Aleksandr Andrukhov Date: Sun, 15 Oct 2023 02:41:41 +0300 Subject: [PATCH 3/3] Update docs/ru/docs/tutorial/request-files.md Co-authored-by: oubush --- docs/ru/docs/tutorial/request-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md index 6055fdbb33cdf..00f8c8377059f 100644 --- a/docs/ru/docs/tutorial/request-files.md +++ b/docs/ru/docs/tutorial/request-files.md @@ -147,7 +147,7 @@ contents = myfile.file.read() !!! note "Технические детали Starlette" **FastAPI** наследует `UploadFile` непосредственно из **Starlette**, но добавляет некоторые детали для совместимости с **Pydantic** и другими частями FastAPI. -## Про "Form Data" +## Про данные формы ("Form Data") Способ, которым HTML-формы (`
`) отправляют данные на сервер, обычно использует "специальную" кодировку для этих данных, отличную от JSON.