Source code for pyrogram.methods.messages.download_media

#  Pyrogram - Telegram MTProto API Client Library for Python
#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
#
#  This file is part of Pyrogram.
#
#  Pyrogram is free software: you can redistribute it and/or modify
#  it under the terms of the GNU Lesser General Public License as published
#  by the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  Pyrogram is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU Lesser General Public License for more details.
#
#  You should have received a copy of the GNU Lesser General Public License
#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.

from __future__ import annotations

import logging
import os
import re
from datetime import datetime
from typing import TYPE_CHECKING

log = logging.getLogger(__name__)

import pyrogram
from pyrogram import types, utils
from pyrogram.file_id import PHOTO_TYPES, FileId, FileType

if TYPE_CHECKING:
    from io import BytesIO
    from collections.abc import Callable

DEFAULT_DOWNLOAD_DIR = "downloads/"
STORY_MEDIA = ("photo", "video")


def safe_file_name(file_name: str) -> str:
    if not file_name:
        return ""

    file_name = os.path.basename(file_name.replace("\\", "/")).replace("\x00", "")

    if file_name in (".", ".."):
        return ""

    return file_name


def story_media(story: types.Story):
    media_type = getattr(story, "media", None)
    kind = getattr(media_type, "value", media_type)

    if isinstance(kind, str):
        media = getattr(story, kind, None)

        if media is not None:
            return media

    for kind in STORY_MEDIA:
        media = getattr(story, kind, None)

        if media is not None:
            return media

    return None


def purchased_paid_media(paid_media_info: types.PaidMediaInfo) -> list | None:
    media = getattr(paid_media_info, "media", None)

    if not media or isinstance(media[0], types.PaidMediaPreview):
        return None

    return media


def save_inline_thumbnail(
    client: pyrogram.Client,
    message: types.StrippedThumbnail | types.PaidMediaPreview,
    file_name: str,
    in_memory: bool,
) -> str | BytesIO:
    if isinstance(message, types.StrippedThumbnail):
        data = message.data
    else:
        data = getattr(getattr(message, "thumbnail", None), "data", None)

    if not data:
        raise ValueError("This message doesn't contain any downloadable media")

    thumbnail = utils.from_inline_bytes(utils.expand_inline_bytes(data))

    if in_memory:
        return thumbnail

    directory, name = os.path.split(file_name)
    name = safe_file_name(name) or thumbnail.name

    if not os.path.isabs(directory):
        directory = client.workdir / (directory or DEFAULT_DOWNLOAD_DIR)

    os.makedirs(directory, exist_ok=True)
    file_path = os.path.abspath(re.sub(r"\\", "/", os.path.join(directory, name)))

    with open(file_path, "wb") as file:
        file.write(thumbnail.getbuffer())

    return file_path


async def download_paid_media(
    client: pyrogram.Client,
    media: list,
    file_name: str,
    in_memory: bool,
    block: bool,
    progress: Callable | None,
    progress_args: tuple,
) -> list[str | BytesIO] | None:
    directory, name = os.path.split(file_name)
    results = []

    for index, item in enumerate(media):
        item_name = name

        if name and len(media) > 1:
            stem, extension = os.path.splitext(name)
            item_name = f"{stem}_{index + 1}{extension}"

        result = await client.download_media(
            item,
            file_name=os.path.join(directory, item_name),
            in_memory=in_memory,
            block=block,
            progress=progress,
            progress_args=progress_args,
        )

        if result is not None:
            results.append(result)

    return results or None


class DownloadMedia:
    async def download_media(
        self: pyrogram.Client,
        message: types.Message | str,
        file_name: str = DEFAULT_DOWNLOAD_DIR,
        in_memory: bool = False,
        block: bool = True,
        progress: Callable | None = None,
        progress_args: tuple = (),
    ) -> str | BytesIO | list[str] | list[BytesIO] | None:
        """Download the media from a message.

        .. include:: /_includes/usable-by/users-bots.rst

        Parameters:
            message (:obj:`~pyrogram.types.Message` | ``str``):
                Pass a Message containing the media, the media itself (message.audio, message.video, ...) or a file id
                as string.

            file_name (``str``, *optional*):
                A custom *file_name* to be used instead of the one provided by Telegram.
                By default, all files are downloaded in the *downloads* folder in your working directory.
                You can also specify a path for downloading files in a custom location: paths that end with "/"
                are considered directories. All non-existent folders will be created automatically.

            in_memory (``bool``, *optional*):
                Pass True to download the media in-memory.
                A binary file-like object with its attribute ".name" set will be returned.
                Defaults to False.

            block (``bool``, *optional*):
                Blocks the code execution until the file has been downloaded.
                Defaults to True.

            progress (``Callable``, *optional*):
                Pass a callback function to view the file transmission progress.
                The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
                detailed description) and will be called back each time a new file chunk has been successfully
                transmitted.

            progress_args (``tuple``, *optional*):
                Extra custom arguments for the progress callback function.
                You can pass anything you need to be available in the progress callback scope; for example, a Message
                object or a Client instance in order to edit the message with the updated progress status.

        Other Parameters:
            current (``int``):
                The amount of bytes transmitted so far.

            total (``int``):
                The total size of the file.

            *args (``tuple``, *optional*):
                Extra custom arguments as defined in the ``progress_args`` parameter.
                You can either keep ``*args`` or add every single extra argument in your function signature.

        Returns:
            ``str`` | ``BytesIO`` | ``list[str]`` | ``list[BytesIO]`` | ``None``: On success, the absolute path of the
            downloaded file is returned. In case ``in_memory=True``, a binary file-like object with its attribute
            ".name" set is returned. If the message contains multiple media (purchased paid media), a list of paths or
            binary file-like objects is returned. In case the download failed or was deliberately stopped with
            :meth:`~pyrogram.Client.stop_transmission`, None is returned.

        Raises:
            ValueError: if the message doesn't contain any downloadable media

        Example:
            Download media to file

            .. code-block:: python

                # Download from Message
                await app.download_media(message)

                # Download from file id
                await app.download_media(message.photo.file_id)

                # Keep track of the progress while downloading
                async def progress(current, total):
                    print(f"{current * 100 / total:.1f}%")

                await app.download_media(message, progress=progress)

            Download media in-memory

            .. code-block:: python

                file = await app.download_media(message, in_memory=True)

                file_name = file.name
                file_bytes = bytes(file.getbuffer())
        """
        available_media = (
            "audio",
            "document",
            "photo",
            "sticker",
            "animation",
            "video",
            "voice",
            "video_note",
            "new_chat_photo",
            "paid_media",
        )

        media = None
        paid_media = None

        if isinstance(message, types.Message):
            story = getattr(message, "story", None) or getattr(message, "reply_to_story", None)

            if story is not None:
                media = story_media(story)
            else:
                for kind in available_media:
                    value = getattr(message, kind, None)

                    if value is None:
                        continue

                    if kind == "paid_media":
                        paid_media = purchased_paid_media(value)
                    else:
                        media = value

                    break
        elif isinstance(message, types.Story):
            media = story_media(message)
        elif isinstance(message, types.PaidMediaInfo):
            paid_media = purchased_paid_media(message)
        elif isinstance(message, (types.StrippedThumbnail, types.PaidMediaPreview)):
            return save_inline_thumbnail(self, message, file_name, in_memory)
        elif isinstance(message, types.ChatPhoto):
            media = message.big_file_id
        else:
            media = message

        if paid_media is not None:
            return await download_paid_media(
                self, paid_media, file_name, in_memory, block, progress, progress_args
            )

        if media is None:
            raise ValueError("This message doesn't contain any downloadable media")

        if isinstance(media, str):
            file_id_str = media
        else:
            file_id_str = media.file_id

        file_id_obj = FileId.decode(file_id_str)

        file_type = file_id_obj.file_type
        media_file_name = getattr(media, "file_name", "")
        file_size = getattr(media, "file_size", 0)
        mime_type = getattr(media, "mime_type", "")
        date = getattr(media, "date", None)

        directory, file_name = os.path.split(file_name)
        file_name = safe_file_name(file_name) or safe_file_name(media_file_name) or ""

        if not os.path.isabs(directory):
            directory = self.workdir / (directory or DEFAULT_DOWNLOAD_DIR)

        if not file_name:
            guessed_extension = self.guess_extension(mime_type)

            if file_type in PHOTO_TYPES:
                extension = ".jpg"
            elif file_type == FileType.VOICE:
                extension = guessed_extension or ".ogg"
            elif file_type in (FileType.VIDEO, FileType.ANIMATION, FileType.VIDEO_NOTE):
                extension = guessed_extension or ".mp4"
            elif file_type == FileType.DOCUMENT:
                extension = guessed_extension or ".zip"
            elif file_type == FileType.STICKER:
                extension = guessed_extension or ".webp"
            elif file_type == FileType.AUDIO:
                extension = guessed_extension or ".mp3"
            else:
                extension = ".unknown"

            file_name = "{}_{}_{}{}".format(
                FileType(file_id_obj.file_type).name.lower(),
                (date or datetime.now()).strftime("%Y-%m-%d_%H-%M-%S"),
                self.rnd_id(),
                extension,
            )

        downloader = self.handle_download(
            (file_id_obj, directory, file_name, in_memory, file_size, progress, progress_args)
        )

        if block:
            return await downloader
        else:

            async def _run_download():
                try:
                    return await downloader
                except Exception as e:
                    log.exception("Background download failed: %s", e)

            utils.run_in_background(_run_download())