diff --git a/readthedocs/misc/v2-migration-guide.rst b/readthedocs/misc/v2-migration-guide.rst index 1ca03003..22bd2acd 100644 --- a/readthedocs/misc/v2-migration-guide.rst +++ b/readthedocs/misc/v2-migration-guide.rst @@ -181,7 +181,6 @@ The following modules have been moved inside ``_misc``: Using the client in a context-manager no longer calls start automatically ------------------------------------------------------------------------- - The following code no longer automatically calls ``client.start()``: .. code-block:: python @@ -210,6 +209,15 @@ Note that you do not need to ``await`` the call to ``.start()`` if you are going in a context-manager (but it's okay if you put the ``await``). +download_file has been removed from the client +---------------------------------------------- + +Instead, ``client.download_media`` should be used. + +The now-removed ``client.download_file`` method was a lower level implementation which should +have not been exposed at all. + + Support for bot-API style file_id has been removed -------------------------------------------------- diff --git a/telethon/_client/downloads.py b/telethon/_client/downloads.py index 53e22cc1..9ae1aec8 100644 --- a/telethon/_client/downloads.py +++ b/telethon/_client/downloads.py @@ -243,7 +243,12 @@ async def download_profile_photo( ) try: - result = await self.download_file(loc, file, dc_id=dc_id) + result = await _download_file( + self=self, + input_location=loc, + file=file, + dc_id=dc_id + ) return result if file is bytes else file except errors.LocationInvalidError: # See issue #500, Android app fails as of v4.6.0 (1155). @@ -308,29 +313,6 @@ async def download_media( self, media, file, progress_callback ) -async def download_file( - self: 'TelegramClient', - input_location: 'hints.FileLike', - file: 'hints.OutFileLike' = None, - *, - part_size_kb: float = None, - file_size: int = None, - progress_callback: 'hints.ProgressCallback' = None, - dc_id: int = None, - key: bytes = None, - iv: bytes = None) -> typing.Optional[bytes]: - return await _download_file( - self, - input_location, - file, - part_size_kb=part_size_kb, - file_size=file_size, - progress_callback=progress_callback, - dc_id=dc_id, - key=key, - iv=iv, - ) - async def _download_file( self: 'TelegramClient', input_location: 'hints.FileLike', @@ -343,6 +325,46 @@ async def _download_file( key: bytes = None, iv: bytes = None, msg_data: tuple = None) -> typing.Optional[bytes]: + """ + Low-level method to download files from their input location. + + Arguments + input_location (:tl:`InputFileLocation`): + The file location from which the file will be downloaded. + See `telethon.utils.get_input_location` source for a complete + list of supported _tl. + + file (`str` | `file`, optional): + The output file path, directory, or stream-like object. + If the path exists and is a file, it will be overwritten. + + If the file path is `None` or `bytes`, then the result + will be saved in memory and returned as `bytes`. + + part_size_kb (`int`, optional): + Chunk size when downloading files. The larger, the less + requests will be made (up to 512KB maximum). + + file_size (`int`, optional): + The file size that is about to be downloaded, if known. + Only used if ``progress_callback`` is specified. + + progress_callback (`callable`, optional): + A callback function accepting two parameters: + ``(downloaded bytes, total)``. Note that the + ``total`` is the provided ``file_size``. + + dc_id (`int`, optional): + The data center the library should connect to in order + to download the file. You shouldn't worry about this. + + key ('bytes', optional): + In case of an encrypted upload (secret chats) a key is supplied + + iv ('bytes', optional): + In case of an encrypted upload (secret chats) an iv is supplied + """ + if not part_size_kb: if not file_size: part_size_kb = 64 # Reasonable default @@ -568,14 +590,15 @@ async def _download_photo(self: 'TelegramClient', photo, file, date, thumb, prog else: file_size = size.size - result = await self.download_file( - _tl.InputPhotoFileLocation( + result = await _download_file( + self=self, + input_location=_tl.InputPhotoFileLocation( id=photo.id, access_hash=photo.access_hash, file_reference=photo.file_reference, thumb_size=size.type ), - file, + file=file, file_size=file_size, progress_callback=progress_callback ) @@ -626,13 +649,14 @@ async def _download_document( return _download_cached_photo_size(self, size, file) result = await _download_file( - _tl.InputDocumentFileLocation( + self=self, + input_location=_tl.InputDocumentFileLocation( id=document.id, access_hash=document.access_hash, file_reference=document.file_reference, thumb_size=size.type if size else '' ), - file, + file=file, file_size=size.size if size else document.size, progress_callback=progress_callback, msg_data=msg_data, diff --git a/telethon/_client/telegramclient.py b/telethon/_client/telegramclient.py index e2f1de76..811ad94b 100644 --- a/telethon/_client/telegramclient.py +++ b/telethon/_client/telegramclient.py @@ -1765,71 +1765,6 @@ class TelegramClient: """ return await downloads.download_media(**locals()) - async def download_file( - self: 'TelegramClient', - input_location: 'hints.FileLike', - file: 'hints.OutFileLike' = None, - *, - part_size_kb: float = None, - file_size: int = None, - progress_callback: 'hints.ProgressCallback' = None, - dc_id: int = None, - key: bytes = None, - iv: bytes = None) -> typing.Optional[bytes]: - """ - Low-level method to download files from their input location. - - .. note:: - - Generally, you should instead use `download_media`. - This method is intended to be a bit more low-level. - - Arguments - input_location (:tl:`InputFileLocation`): - The file location from which the file will be downloaded. - See `telethon.utils.get_input_location` source for a complete - list of supported _tl. - - file (`str` | `file`, optional): - The output file path, directory, or stream-like object. - If the path exists and is a file, it will be overwritten. - - If the file path is `None` or `bytes`, then the result - will be saved in memory and returned as `bytes`. - - part_size_kb (`int`, optional): - Chunk size when downloading files. The larger, the less - requests will be made (up to 512KB maximum). - - file_size (`int`, optional): - The file size that is about to be downloaded, if known. - Only used if ``progress_callback`` is specified. - - progress_callback (`callable`, optional): - A callback function accepting two parameters: - ``(downloaded bytes, total)``. Note that the - ``total`` is the provided ``file_size``. - - dc_id (`int`, optional): - The data center the library should connect to in order - to download the file. You shouldn't worry about this. - - key ('bytes', optional): - In case of an encrypted upload (secret chats) a key is supplied - - iv ('bytes', optional): - In case of an encrypted upload (secret chats) an iv is supplied - - - Example - .. code-block:: python - - # Download a file and print its header - data = await client.download_file(input_file, bytes) - print(data[:16]) - """ - return await downloads.download_file(**locals()) - def iter_download( self: 'TelegramClient', file: 'hints.FileLike',