Skip to content
Back to top
View this page

# 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.

    Changed in version 21.7: Raises `RuntimeError` if `file_path` is not set. Note that files without a `file_path` could never be downloaded, as this attribute is mandatory for that operation.

    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`.

        Added in version 20.0.

      - write_timeout (`float` | `None`, optional) –

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

        Added in version 20.0.

      - connect_timeout (`float` | `None`, optional) –

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

        Added in version 20.0.

      - pool_timeout (`float` | `None`, optional) –

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

        Added in version 20.0.

    Returns:

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

    Return type:

      `bytearray`

    Raises:

      RuntimeError – If `file_path` is not set.

  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 `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()`.

    Changed in version 21.7: Raises `RuntimeError` if `file_path` is not set. Note that files without a `file_path` could never be downloaded, as this attribute is mandatory for that operation.

    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`

    Raises:

      RuntimeError – If `file_path` is not set.

  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

    Hint

    If you want to immediately read the data from `out` after calling this method, you should call `out.seek(0)` first. See also `io.IOBase.seek()`.

    Added in version 20.0.

    Changed in version 21.7: Raises `RuntimeError` if `file_path` is not set. Note that files without a `file_path` could never be downloaded, as this attribute is mandatory for that operation.

    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`.

    Raises:

      RuntimeError – If `file_path` is not set.

  set_credentials(credentials)

    Sets the passport credentials for the file.

    Parameters:

      credentials (`telegram.FileCredentials`) – The credentials.