Function parse_file_input

src/telegram/_utils/files.py:98–160

Parses input for sending files: * For string input, if the input is an absolute path of a local file: * if ``local_mode`` is ``True``, adds the ``file://`` prefix. If the input is a relative path of a local file, computes the absolute path and adds the ``file://`` prefix.

(  # pylint: disable=too-many-return-statements
    file_input: "FileInput | TelegramObject",
    tg_type: type["TelegramObject"] | None = None,
    filename: str | None = None,
    attach: bool = False,
    local_mode: bool = False,
)

def parse_file_input(  # pylint: disable=too-many-return-statements
    file_input: "FileInput | TelegramObject",
    tg_type: type["TelegramObject"] | None = None,
    filename: str | None = None,
    attach: bool = False,
    local_mode: bool = False,
) -> "str | InputFile | Any":
    """
    Parses input for sending files:

    * For string input, if the input is an absolute path of a local file:

        * if ``local_mode`` is ``True``, adds the ``file://`` prefix. If the input is a relative
        path of a local file, computes the absolute path and adds the ``file://`` prefix.
        * if ``local_mode`` is ``False``, loads the file as binary data and builds an
          :class:`InputFile` from that

      Returns the input unchanged, otherwise.
    * :class:`pathlib.Path` objects are treated the same way as strings.
    * For IO and bytes input, returns an :class:`telegram.InputFile`.
    * If :attr:`tg_type` is specified and the input is of that type, returns the ``file_id``
      attribute.

    Args:
        file_input (:obj:`str` | :obj:`bytes` | :term:`file object` | :class:`~telegram.InputFile`\
            | Telegram media object): The input to parse.
        tg_type (:obj:`type`, optional): The Telegram media type the input can be. E.g.
            :class:`telegram.Animation`.
        filename (:obj:`str`, optional): The filename. Only relevant in case an
            :class:`telegram.InputFile` is returned.
        attach (:obj:`bool`, optional): Pass :obj:`True` if the parameter this file belongs to in
            the request to Telegram should point to the multipart data via an ``attach://`` URI.
            Defaults to `False`. Only relevant if an :class:`telegram.InputFile` is returned.
        local_mode (:obj:`bool`, optional): Pass :obj:`True` if the bot is running an api server
            in ``--local`` mode.

    Returns:
        :obj:`str` | :class:`telegram.InputFile` | :obj:`object`: The parsed input or the untouched
        :attr:`file_input`, in case it's no valid file input.
    """
    # Importing on file-level yields cyclic Import Errors
    from telegram import InputFile  # pylint: disable=import-outside-toplevel  # noqa: PLC0415

    if isinstance(file_input, str) and file_input.startswith("file://"):
        if not local_mode:
            raise ValueError("Specified file input is a file URI, but local mode is not enabled.")
        return file_input
    if isinstance(file_input, str | Path):
        if is_local_file(file_input):
            path = Path(file_input)
            if local_mode:
                return path.absolute().as_uri()
            with path.open(mode="rb") as file_handle:
                return InputFile(file_handle, filename=filename, attach=attach)

        return file_input
    if isinstance(file_input, bytes):
        return InputFile(file_input, filename=filename, attach=attach)