telegram.File

class telegram.File(*args, **kwargs)[source]

Bases: telegram.TelegramObject

This object represents a file ready to be downloaded. The file can be downloaded with download. 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.

Note

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 download to get the file.

  • bot (telegram.Bot, optional) – Bot to use with shortcut method.

  • **kwargs (dict) – Arbitrary keyword arguments.

file_id[source]

Identifier for this file.

Type

str

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

str

file_size[source]

Optional. File size in bytes.

Type

str

file_path[source]

Optional. File path. Use download() to get the file.

Type

str

async download(custom_path=None, out=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, it the file ID will be used as filename. If a custom_path is supplied, it will be saved to that path instead. If out is defined, the file contents will be saved to that object using the out.write method.

Note

  • custom_path and out are mutually exclusive.

  • If neither custom_path nor out is 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.

Changed in version 20.0:

Parameters
Returns

The same object as out if

specified. Otherwise, returns the filename downloaded to or the file path of the local file.

Return type

pathlib.Path | io.BufferedWriter

Raises

ValueError – If both custom_path and out are passed.

async download_as_bytearray(buf=None)[source]

Download this file and return it as a bytearray.

Parameters

buf (bytearray, optional) – Extend the given bytearray with the downloaded data.

Returns

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

newly allocated bytearray.

Return type

bytearray

set_credentials(credentials)[source]

Sets the passport credentials for the file.

Parameters

credentials (telegram.FileCredentials) – The credentials.