telegram.File¶
- class telegram.File(file_id, file_unique_id, file_size=None, file_path=None, *, api_kwargs=None)[source]¶
Bases:
telegram.TelegramObject
This object represents a file ready to be downloaded. The file can be e.g. downloaded with
download_to_memory
. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by callingtelegram.Bot.get_file()
.Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their
file_unique_id
is equal.Changed in version 20.0::
download
was split intodownload_to_memory()
anddownload_to_object()
.Note
Maximum file size to download is
20 MB
.If you obtain an instance of this class from
telegram.PassportFile.get_file
, then it will automatically be decrypted as it downloads when you call e.g.download_to_memory()
.
- Parameters
file_id (
str
) – Identifier for this file, which can be used to download or reuse the file.file_unique_id (
str
) – Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.file_size (
int
, optional) – Optional. File size in bytes, if known.file_path (
str
, optional) – File path. Use e.g.download_to_memory()
to get the file.
- file_unique_id[source]¶
Unique identifier for this file, which is supposed to be the same over time and for different bots. Can’t be used to download or reuse the file.
- Type
- file_path[source]¶
Optional. File path. Use e.g.
download_to_memory()
to get the file.- Type
- async download_to_memory(custom_path=None, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)[source]¶
Download this file. By default, the file is saved in the current working directory with its original filename as reported by Telegram. If the file has no filename, the file ID will be used as filename. If
custom_path
is supplied as astr
orpathlib.Path
, it will be saved to that path.Note
- If
custom_path
isn’t provided andfile_path
is the path of a local file (which is the case when a Bot API Server is running in local mode), this method will just return the path.
- The only exception to this are encrypted files (e.g. a passport file). For these, a
file with the prefix decrypted_ will be created in the same directory as the original file in order to decrypt the file without changing the existing one in-place.
Changed in version 20.0:
custom_path
parameter now also acceptspathlib.Path
as argument.Returns
pathlib.Path
object in cases where previously astr
was returned.This method was previously called
download
. It was split intodownload_to_memory()
anddownload_to_object()
.
- Parameters
custom_path (
pathlib.Path
|str
, optional) – The path where the file will be saved to. If not specified, will be saved in the current working directory.read_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.read_timeout
. Defaults toDEFAULT_NONE
.write_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.write_timeout
. Defaults toDEFAULT_NONE
.connect_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.connect_timeout
. Defaults toDEFAULT_NONE
.pool_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.pool_timeout
. Defaults toDEFAULT_NONE
.
- Returns
Returns the Path object the file was downloaded to.
- Return type
- If
- async download_to_object(out, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)[source]¶
Download this file into memory.
out
needs to be supplied with aio.BufferedIOBase
, the file contents will be saved to that object using theout.write
method.New in version 20.0.
- Parameters
out (
io.BufferedIOBase
) – A file-like object. Must be opened for writing in binary mode.read_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.read_timeout
. Defaults toDEFAULT_NONE
.write_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.write_timeout
. Defaults toDEFAULT_NONE
.connect_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.connect_timeout
. Defaults toDEFAULT_NONE
.pool_timeout (
float
|None
, optional) – Value to pass totelegram.request.BaseRequest.post.pool_timeout
. Defaults toDEFAULT_NONE
.
- set_credentials(credentials)[source]¶
Sets the passport credentials for the file.
- Parameters
credentials (
telegram.FileCredentials
) – The credentials.