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_drive
. 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.Available In
Changed in version 20.0:
download
was split intodownload_to_drive()
anddownload_to_memory()
.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_drive()
.
- 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_path (
str
, optional) – File path. Use e.g.download_to_drive()
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_drive()
to get the file.- Type:
- async download_as_bytearray(buf=None, *, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)[source]¶
Download this file and return it as a bytearray.
- Parameters:
buf (
bytearray
, optional) – Extend the given bytearray with the downloaded data.- Keyword Arguments:
read_timeout (
float
|None
, optional) –Value to pass to
telegram.request.BaseRequest.post.read_timeout
. Defaults toDEFAULT_NONE
.New in version 20.0.
write_timeout (
float
|None
, optional) –Value to pass to
telegram.request.BaseRequest.post.write_timeout
. Defaults toDEFAULT_NONE
.New in version 20.0.
connect_timeout (
float
|None
, optional) –Value to pass to
telegram.request.BaseRequest.post.connect_timeout
. Defaults toDEFAULT_NONE
.New in version 20.0.
pool_timeout (
float
|None
, optional) –Value to pass to
telegram.request.BaseRequest.post.pool_timeout
. Defaults toDEFAULT_NONE
.New in version 20.0.
- Returns:
The same object as
buf
if it was specified. Otherwise a newly allocatedbytearray
.- Return type:
- async download_to_drive(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
file_path
as file name. If the file has no filename, the file ID will be used as filename. Ifcustom_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.
See also
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_drive()
anddownload_to_memory()
.
- 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 withfile_path
as file name or thefile_id
iffile_path
is not set.- Keyword Arguments:
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:
- async download_to_memory(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.See also
New in version 20.0.
- Parameters:
out (
io.BufferedIOBase
) – A file-like object. Must be opened for writing in binary mode.- Keyword Arguments:
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.