From fa6732542d44c57b60b759a178ba1ce5a18aff04 Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Wed, 20 Nov 2019 00:10:52 +0200 Subject: [PATCH] Add instruction how to upload files --- docs/api/sending_files.md | 67 +++++++++++++++++++++++++ docs/api/types/input_file.md | 2 +- docs/api/types/input_media_animation.md | 1 + docs/api/types/input_media_audio.md | 1 + docs/api/types/input_media_document.md | 1 + docs/api/types/input_media_photo.md | 1 + docs/api/types/input_media_video.md | 1 + mkdocs.yml | 1 + 8 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 docs/api/sending_files.md diff --git a/docs/api/sending_files.md b/docs/api/sending_files.md new file mode 100644 index 00000000..02e14599 --- /dev/null +++ b/docs/api/sending_files.md @@ -0,0 +1,67 @@ +# How to upload file? + +As says [official Telegram Bot API documentation](https://core.telegram.org/bots/api#sending-files) there are three ways to send files (photos, stickers, audio, media, etc.): + +If the file is already stored somewhere on the Telegram servers or file is available by the URL, you don't need to reupload it. +But if you need to upload new file just use subclasses of [InputFile](./types/input_file.md). Here is available two different types of input file: + +- `#!python3 FSInputFile` - [uploading from file system](#upload-from-file-system) +- `#!python3 BufferedInputFile` - [uploading from buffer](#upload-from-buffer) + +!!! warning "Be respectful with Telegram" + Instances of `InputFile` is reusable. That's mean you can create instance of InputFile and sent this file multiple times but Telegram is not recommend to do that and when you upload file once just save their `file_id` and use it in next times. + +## Upload from file system +By first step you will need to import InputFile wrapper: +```python3 +from aiogram.types import FSInputFile +``` + +Then you can use it: +```python3 +cat = FSInputFile("cat.png") +agenda = FSInputFile("my-document.pdf", filename="agenda-2019-11-19.pdf") +``` + +### FSInputFile(...) + +|Argument|Type|Description| +|---|---|---| +| path | `#!python3 Union[str, Path]` | File path | +| filename | `#!python3 Optional[str]` | Custom filename to be presented to Telegram | +| chunk_size | `#!python3 int` | File chunks size (Default: `64 kb`) | + +## Upload from buffer + +Files can be also passed from buffer (For example you generate image using [Pillow](https://pillow.readthedocs.io/en/stable/) and the want's to sent it to the Telegram): + +Import wrapper: + +```python3 +from aiogram.types import BufferedInputFile +``` + +And then you can use it: +```python3 +text_file = BufferedInputFile(b"Hello, world!", filename="file.txt") +``` + +### BufferedInputFile(...) +|Argument|Type|Description| +|---|---|---| +| buffer | `#!python3 bytes` | File path | +| filename | `#!python3 str` | Custom filename to be presented to Telegram (Required) | +| chunk_size | `#!python3 int` | File chunks size (Default: `64 kb`) | + +Also you can read buffer from file: + +```python3 +file = BufferedInputFile.from_file("file.txt") +``` + +### BufferedInputFile.from_file(...) +|Argument|Type|Description| +|---|---|---| +| path | `#!python3 Union[str, Path]` | File path | +| filename | `#!python3 Optional[str]` | Custom filename to be presented to Telegram | +| chunk_size | `#!python3 int` | File chunks size (Default: `64 kb`) | diff --git a/docs/api/types/input_file.md b/docs/api/types/input_file.md index 6df45d71..ca034c7f 100644 --- a/docs/api/types/input_file.md +++ b/docs/api/types/input_file.md @@ -14,5 +14,5 @@ This object represents the contents of a file to be uploaded. Must be posted usi - `from aiogram.api.types.input_file import InputFile` ## Related pages: - - [Official documentation](https://core.telegram.org/bots/api#inputfile) +- [How to upload file?](../sending_files.md) diff --git a/docs/api/types/input_media_animation.md b/docs/api/types/input_media_animation.md index fbf5c53b..ce0c3132 100644 --- a/docs/api/types/input_media_animation.md +++ b/docs/api/types/input_media_animation.md @@ -30,3 +30,4 @@ Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be - [Official documentation](https://core.telegram.org/bots/api#inputmediaanimation) - [aiogram.types.InputFile](../types/input_file.md) +- [How to upload file?](../sending_files.md) diff --git a/docs/api/types/input_media_audio.md b/docs/api/types/input_media_audio.md index c1f4d1a7..dac0d773 100644 --- a/docs/api/types/input_media_audio.md +++ b/docs/api/types/input_media_audio.md @@ -30,3 +30,4 @@ Represents an audio file to be treated as music to be sent. - [Official documentation](https://core.telegram.org/bots/api#inputmediaaudio) - [aiogram.types.InputFile](../types/input_file.md) +- [How to upload file?](../sending_files.md) diff --git a/docs/api/types/input_media_document.md b/docs/api/types/input_media_document.md index e45ecd2f..77877ebe 100644 --- a/docs/api/types/input_media_document.md +++ b/docs/api/types/input_media_document.md @@ -27,3 +27,4 @@ Represents a general file to be sent. - [Official documentation](https://core.telegram.org/bots/api#inputmediadocument) - [aiogram.types.InputFile](../types/input_file.md) +- [How to upload file?](../sending_files.md) diff --git a/docs/api/types/input_media_photo.md b/docs/api/types/input_media_photo.md index 29559ea1..29c903e6 100644 --- a/docs/api/types/input_media_photo.md +++ b/docs/api/types/input_media_photo.md @@ -26,3 +26,4 @@ Represents a photo to be sent. - [Official documentation](https://core.telegram.org/bots/api#inputmediaphoto) - [aiogram.types.InputFile](../types/input_file.md) +- [How to upload file?](../sending_files.md) diff --git a/docs/api/types/input_media_video.md b/docs/api/types/input_media_video.md index 41f47b3a..5a45d03d 100644 --- a/docs/api/types/input_media_video.md +++ b/docs/api/types/input_media_video.md @@ -31,3 +31,4 @@ Represents a video to be sent. - [Official documentation](https://core.telegram.org/bots/api#inputmediavideo) - [aiogram.types.InputFile](../types/input_file.md) +- [How to upload file?](../sending_files.md) diff --git a/mkdocs.yml b/mkdocs.yml index d6639371..98585311 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -211,6 +211,7 @@ nav: - api/types/game.md - api/types/callback_game.md - api/types/game_high_score.md + - api/sending_files.md - Build reports: - Tests result: /reports/tests - Code coverage: /reports/coverage