Download feature and URLInputFile (#332)

* Fix How to upload docs

* Rename BaseBot to Bot

* Add download_file method

* Add download method

* Add URLInputFile

* Add Downloadable to __init__ and __all__

* Fix ImportError for Python 3.7

* Related pages

* Improving docs

* Some speed

* staticmethod to classmethod

docs/api/download_file.md

@@ -0,0 +1,106 @@
+# How to download file?
+## Download file manually
+First, you must get the `file_id` of the file you want to download. Information about files sent to the bot is contained in [Message](./types/message.md).
+
+For example, download the document that came to the bot.
+```python3
+file_id = message.document.file_id
+```
+
+Then use the [getFile](./methods/get_file.md) method to get `file_path`.
+```python3
+file = await bot.get_file(file_id)
+file_path = file.file_path
+```
+
+After that, use the [download_file](#download_file) method from the bot object.
+
+### download_file(...)
+
+Download file by `file_path` to destination.
+
+If you want to automatically create destination (`#!python3 io.BytesIO`) use default
+value of destination and handle result of this method.
+
+|Argument|Type|Description|
+|---|---|---|
+| file_path | `#!python3 str` | File path on Telegram server |
+| destination | `#!python3 Optional[Union[BinaryIO, pathlib.Path, str]]` | Filename, file path or instance of `#!python3 io.IOBase`. For e.g. `#!python3 io.BytesIO` (Default: `#!python3 None`) |
+| timeout | `#!python3 int` | Total timeout in seconds (Default: `30`) |
+| chunk_size | `#!python3 int` | File chunks size (Default: `64 kb`) |
+| seek | `#!python3 bool` | Go to start of file when downloading is finished. Used only for destination with `#!python3 typing.BinaryIO` type (Default: `#!python3 True`) |
+
+There are two options where you can download the file: to **disk** or to **binary I/O object**.
+
+### Download file to disk
+
+To download file to disk, you must specify the file name or path where to download the file. In this case, the function will return nothing. 
+
+```python3
+await bot.download_file(file_path, "text.txt")
+```
+
+### Download file to binary I/O object
+
+To download file to binary I/O object, you must specify an object with the `#!python3 typing.BinaryIO` type or use the default (`#!python3 None`) value.
+
+In the first case, the function will return your object:
+```python3
+my_object = MyBinaryIO()
+result: MyBinaryIO = await bot.download_file(file_path, my_object)
+# print(result is my_object)  # True
+```
+
+If you leave the default value, an `#!python3 io.BytesIO` object will be created and returned.
+
+```python3
+result: io.BytesIO = await bot.download_file(file_path)
+```
+
+## Download file in short way
+
+Getting `file_path` manually every time is boring, so you should use the [download](#download) method.
+
+### download(...)
+
+Download file by `file_id` or `Downloadable` object to destination.
+
+If you want to automatically create destination (`#!python3 io.BytesIO`) use default
+value of destination and handle result of this method.
+
+|Argument|Type|Description|
+|---|---|---|
+| file | `#!python3 Union[str, Downloadable]` | file_id or Downloadable object |
+| destination | `#!python3 Optional[Union[BinaryIO, pathlib.Path, str]]` | Filename, file path or instance of `#!python3 io.IOBase`. For e.g. `#!python3 io.BytesIO` (Default: `#!python3 None`) |
+| timeout | `#!python3 int` | Total timeout in seconds (Default: `30`) |
+| chunk_size | `#!python3 int` | File chunks size (Default: `64 kb`) |
+| seek | `#!python3 bool` | Go to start of file when downloading is finished. Used only for destination with `#!python3 typing.BinaryIO` type (Default: `#!python3 True`) |
+
+It differs from [download_file](#download_file) **only** in that it accepts `file_id` or an `Downloadable` object (object that contains the `file_id` attribute) instead of `file_path`.
+
+!!! note
+    All `Downloadable` objects are listed in Related pages.
+
+You can download a file to [disk](#download-file-to-disk) or to a [binary I/O](#download-file-to-binary-io-object) object in the same way.
+
+Example:
+
+```python3
+document = message.document
+await bot.download(document)
+```
+
+## Related pages:
+
+- [Official documentation](https://core.telegram.org/bots/api#getfile)
+- [aiogram.types.Animation](types/animation.md)
+- [aiogram.types.Audio](types/audio.md)
+- [aiogram.types.Document](types/document.md)
+- [aiogram.types.File](types/file.md)
+- [aiogram.types.PassportFile](types/passport_file.md)
+- [aiogram.types.PhotoSize](types/photo_size.md)
+- [aiogram.types.Sticker](types/sticker.md)
+- [aiogram.types.Video](types/video.md)
+- [aiogram.types.VideoNote](types/video_note.md)
+- [aiogram.types.Voice](types/voice.md)
+- [How to upload file?](upload_file.md)

docs/api/methods/add_sticker_to_set.md

@@ -61,4 +61,4 @@ return AddStickerToSet(...)
 - [Official documentation](https://core.telegram.org/bots/api#addstickertoset)
 - [aiogram.types.InputFile](../types/input_file.md)
 - [aiogram.types.MaskPosition](../types/mask_position.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/create_new_sticker_set.md

@@ -63,4 +63,4 @@ return CreateNewStickerSet(...)
 - [Official documentation](https://core.telegram.org/bots/api#createnewstickerset)
 - [aiogram.types.InputFile](../types/input_file.md)
 - [aiogram.types.MaskPosition](../types/mask_position.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_animation.md

@@ -70,4 +70,4 @@ return SendAnimation(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_audio.md

@@ -72,4 +72,4 @@ return SendAudio(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_document.md

@@ -67,4 +67,4 @@ return SendDocument(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_photo.md

@@ -66,4 +66,4 @@ return SendPhoto(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_sticker.md

@@ -64,4 +64,4 @@ return SendSticker(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_video.md

@@ -71,4 +71,4 @@ return SendVideo(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_video_note.md

@@ -67,4 +67,4 @@ return SendVideoNote(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/send_voice.md

@@ -67,4 +67,4 @@ return SendVoice(...)
 - [aiogram.types.Message](../types/message.md)
 - [aiogram.types.ReplyKeyboardMarkup](../types/reply_keyboard_markup.md)
 - [aiogram.types.ReplyKeyboardRemove](../types/reply_keyboard_remove.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/set_chat_photo.md

@@ -53,4 +53,4 @@ result: bool = await bot(SetChatPhoto(...))
 
 - [Official documentation](https://core.telegram.org/bots/api#setchatphoto)
 - [aiogram.types.InputFile](../types/input_file.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/set_sticker_set_thumb.md

@@ -57,4 +57,4 @@ return SetStickerSetThumb(...)
 
 - [Official documentation](https://core.telegram.org/bots/api#setstickersetthumb)
 - [aiogram.types.InputFile](../types/input_file.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/set_webhook.md

@@ -70,4 +70,4 @@ return SetWebhook(...)
 
 - [Official documentation](https://core.telegram.org/bots/api#setwebhook)
 - [aiogram.types.InputFile](../types/input_file.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/methods/upload_sticker_file.md

@@ -54,4 +54,4 @@ result: File = await bot(UploadStickerFile(...))
 - [Official documentation](https://core.telegram.org/bots/api#uploadstickerfile)
 - [aiogram.types.File](../types/file.md)
 - [aiogram.types.InputFile](../types/input_file.md)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/types/animation.md

@@ -31,3 +31,4 @@ This object represents an animation file (GIF or H.264/MPEG-4 AVC video without
 
 - [Official documentation](https://core.telegram.org/bots/api#animation)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/audio.md

@@ -30,3 +30,4 @@ This object represents an audio file to be treated as music by the Telegram clie
 
 - [Official documentation](https://core.telegram.org/bots/api#audio)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/document.md

@@ -28,3 +28,4 @@ This object represents a general file (as opposed to photos, voice messages and
 
 - [Official documentation](https://core.telegram.org/bots/api#document)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/file.md

@@ -27,3 +27,4 @@ Maximum file size to download is 20 MB
 ## Related pages:
 
 - [Official documentation](https://core.telegram.org/bots/api#file)
+- [How to download file?](../download_file.md)

docs/api/types/input_file.md

@@ -16,4 +16,4 @@ This object represents the contents of a file to be uploaded. Must be posted usi
 ## Related pages:
 
 - [Official documentation](https://core.telegram.org/bots/api#inputfile)
-- [How to upload file?](../sending_files.md)
+- [How to upload file?](../upload_file.md)

docs/api/types/input_media_animation.md

@@ -30,4 +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)
+- [How to upload file?](../upload_file.md)

docs/api/types/input_media_audio.md

@@ -30,4 +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)
+- [How to upload file?](../upload_file.md)

docs/api/types/input_media_document.md

@@ -27,4 +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)
+- [How to upload file?](../upload_file.md)

docs/api/types/input_media_photo.md

@@ -26,4 +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)
+- [How to upload file?](../upload_file.md)

docs/api/types/input_media_video.md

@@ -31,4 +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)
+- [How to upload file?](../upload_file.md)

docs/api/types/passport_file.md

@@ -25,3 +25,4 @@ This object represents a file uploaded to Telegram Passport. Currently all Teleg
 ## Related pages:
 
 - [Official documentation](https://core.telegram.org/bots/api#passportfile)
+- [How to download file?](../download_file.md)

docs/api/types/photo_size.md

@@ -26,3 +26,4 @@ This object represents one size of a photo or a file / sticker thumbnail.
 ## Related pages:
 
 - [Official documentation](https://core.telegram.org/bots/api#photosize)
+- [How to download file?](../download_file.md)

docs/api/types/sticker.md

@@ -33,3 +33,4 @@ This object represents a sticker.
 - [Official documentation](https://core.telegram.org/bots/api#sticker)
 - [aiogram.types.MaskPosition](../types/mask_position.md)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/video.md

@@ -30,3 +30,4 @@ This object represents a video file.
 
 - [Official documentation](https://core.telegram.org/bots/api#video)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/video_note.md

@@ -28,3 +28,4 @@ This object represents a video message (available in Telegram apps as of v.4.0).
 
 - [Official documentation](https://core.telegram.org/bots/api#videonote)
 - [aiogram.types.PhotoSize](../types/photo_size.md)
+- [How to download file?](../download_file.md)

docs/api/types/voice.md

@@ -26,3 +26,4 @@ This object represents a voice note.
 ## Related pages:
 
 - [Official documentation](https://core.telegram.org/bots/api#voice)
+- [How to download file?](../download_file.md)

docs/api/upload_file.md

@@ -3,10 +3,11 @@
 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:
+But if you need to upload new file just use subclasses of [InputFile](./types/input_file.md). Here is available three different builtin types of input file:
 
 - `#!python3 FSInputFile` - [uploading from file system](#upload-from-file-system)
 - `#!python3 BufferedInputFile` - [uploading from buffer](#upload-from-buffer)
+- `#!python3 URLInputFile` - [uploading from URL](#upload-from-url)
 
 !!! 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.
@@ -65,3 +66,32 @@ file = BufferedInputFile.from_file("file.txt")
 | `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 url
+
+If you need to upload a file from another server, but the direct link is bound to your server's IP, or you want to bypass native [upload limits](https://core.telegram.org/bots/api#sending-files) by URL, you can use [URLInputFile](#urlinputfile).
+
+Import wrapper:
+
+```python3
+from aiogram.types import URLInputFile
+```
+
+And then you can use it:
+```python3
+image = URLInputFile("https://www.python.org/static/community_logos/python-powered-h-140x182.png", filename="logo.png")
+```
+
+### URLInputFile(...)
+|Argument|Type|Description|
+|---|---|---|
+| `url` | `#!python3 str` | URL |
+| `filename` | `#!python3 Optional[str]` | Custom filename to be presented to Telegram |
+| `chunk_size` | `#!python3 int` | File chunks size (Default: `64 kb`) |
+| `timeout` | `#!python3 int` | Total timeout in seconds (Default: `30`) |
+
+## Related pages:
+
+- [Official documentation](https://core.telegram.org/bots/api#sending-files)
+- [aiogram.types.InputFile](types/input_file.md)
+- [How to download file?](download_file.md)