File

class telegram.File(file_id, file_unique_id, file_size=None, file_path=None, *, api_kwargs=None)

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 calling telegram.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

telegram.Sticker.premium_animation

Returned In

• telegram.Bot.get_file()

• telegram.Bot.upload_sticker_file()

Changed in version 20.0: download was split into download_to_drive() and download_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_size (int, optional) – File size in bytes, if known.

• file_path (str, optional) – File path. Use e.g. download_to_drive() to get the file.

file_id

Identifier for this file, which can be used to download or reuse the file.

Type:

str

file_unique_id

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:

str

file_size

Optional. File size in bytes, if known.

Type:

int

file_path

Optional. File path. Use e.g. download_to_drive() to get the file.

Type:

str

async download_as_bytearray(buf=None, *, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

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 to DEFAULT_NONE.

  New in version 20.0.

• write_timeout (float | None, optional) –

  Value to pass to telegram.request.BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

  New in version 20.0.

• connect_timeout (float | None, optional) –

  Value to pass to telegram.request.BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.

  New in version 20.0.

• pool_timeout (float | None, optional) –

  Value to pass to telegram.request.BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

  New in version 20.0.

Returns:

The same object as buf if it was specified. Otherwise a newly allocated bytearray.

Return type:

bytearray

async download_to_drive(custom_path=None, *, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

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. If custom_path is supplied as a str or pathlib.Path, it will be saved to that path.

Note

If custom_path isn’t provided and file_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

Working with Files and Media

Changed in version 20.0:

• custom_path parameter now also accepts pathlib.Path as argument.

• Returns pathlib.Path object in cases where previously a str was returned.

• This method was previously called download. It was split into download_to_drive() and download_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 with file_path as file name or the file_id if file_path is not set.

Keyword Arguments:

• read_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.

• write_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

• connect_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.

• pool_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

Returns:

Returns the Path object the file was downloaded to.

Return type:

pathlib.Path

async download_to_memory(out, *, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

Download this file into memory. out needs to be supplied with a io.BufferedIOBase, the file contents will be saved to that object using the out.write method.

See also

Working with Files and Media

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 to telegram.request.BaseRequest.post.read_timeout. Defaults to DEFAULT_NONE.

• write_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.write_timeout. Defaults to DEFAULT_NONE.

• connect_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.connect_timeout. Defaults to DEFAULT_NONE.

• pool_timeout (float | None, optional) – Value to pass to telegram.request.BaseRequest.post.pool_timeout. Defaults to DEFAULT_NONE.

set_credentials(credentials)

Sets the passport credentials for the file.

Parameters:

credentials (telegram.FileCredentials) – The credentials.