Remove client.edit_folder

Not happy with the design, and keeping it would mean
having to maintain it. It can be added back with a better design.

readthedocs/misc/v2-migration-guide.rst

@@ -771,6 +771,12 @@ The ``client.upload_file`` method has been removed. It's a low-level method user
 to use. Its only purpose could have been to implement a cache of sorts, but this is something the
 library needs to do, not the users.
 
+The methods to deal with folders have been removed. The goal is to find and offer a better
+interface to deal with both folders and archived chats in the future if there is demand for it.
+This includes the removal of ``client.edit_folder``, ``Dialog.archive``, ``Dialog.archived``, and
+the ``archived`` parameter of ``client.get_dialogs``. The ``folder`` parameter remains as it's
+unlikely to change.
+
 
 Deleting messages now returns a more useful value
 -------------------------------------------------

readthedocs/quick-references/client-reference.rst

@@ -103,7 +103,6 @@ Dialogs
 
     iter_dialogs
     get_dialogs
-    edit_folder
     iter_drafts
     get_drafts
     delete_dialog

telethon/_client/dialogs.py

@@ -150,11 +150,7 @@ def get_dialogs(
         ignore_pinned: bool = False,
         ignore_migrated: bool = False,
         folder: int = None,
-        archived: bool = None
 ) -> _DialogsIter:
-    if archived is not None:
-        folder = 1 if archived else 0
-
     return _DialogsIter(
         self,
         limit,
@@ -180,39 +176,6 @@ def get_drafts(
     return _DraftsIter(self, limit, entities=entity)
 
 
-async def edit_folder(
-        self: 'TelegramClient',
-        entity: 'hints.EntitiesLike' = None,
-        folder: typing.Union[int, typing.Sequence[int]] = None,
-        *,
-        unpack=None
-) -> _tl.Updates:
-    if (entity is None) == (unpack is None):
-        raise ValueError('You can only set either entities or unpack, not both')
-
-    if unpack is not None:
-        return await self(_tl.fn.folders.DeleteFolder(
-            folder_id=unpack
-        ))
-
-    if not utils.is_list_like(entity):
-        entities = [await self.get_input_entity(entity)]
-    else:
-        entities = await asyncio.gather(
-            *(self.get_input_entity(x) for x in entity))
-
-    if folder is None:
-        raise ValueError('You must specify a folder')
-    elif not utils.is_list_like(folder):
-        folder = [folder] * len(entities)
-    elif len(entities) != len(folder):
-        raise ValueError('Number of folders does not match number of entities')
-
-    return await self(_tl.fn.folders.EditPeerFolders([
-        _tl.InputFolderPeer(x, folder_id=y)
-        for x, y in zip(entities, folder)
-    ]))
-
 async def delete_dialog(
         self: 'TelegramClient',
         entity: 'hints.EntityLike',

telethon/_client/telegramclient.py

@@ -1390,7 +1390,6 @@ class TelegramClient:
             ignore_pinned: bool = False,
             ignore_migrated: bool = False,
             folder: int = None,
-            archived: bool = None
     ) -> dialogs._DialogsIter:
         """
         Iterator over the dialogs (open conversations/subscribed channels).
@@ -1445,10 +1444,6 @@ class TelegramClient:
                 By default Telegram assigns the folder ID ``1`` to
                 archived chats, so you should use that if you need
                 to fetch the archived dialogs.
-
-            archived (`bool`, optional):
-                Alias for `folder`. If unspecified, all will be returned,
-                `False` implies ``folder=0`` and `True` implies ``folder=1``.
         Yields
             Instances of `Dialog <telethon.tl._custom.dialog.Dialog>`.
 
@@ -1469,11 +1464,9 @@ class TelegramClient:
 
                 # Getting only non-archived dialogs (both equivalent)
                 non_archived = await client.get_dialogs(folder=0, limit=None)
-                non_archived = await client.get_dialogs(archived=False, limit=None)
 
                 # Getting only archived dialogs (both equivalent)
                 archived = await client.get_dialogs(folder=1, limit=None)
-                archived = await client.get_dialogs(archived=True, limit=None)
         """
 
     @forward_call(dialogs.get_drafts)
@@ -1510,65 +1503,6 @@ class TelegramClient:
                 print(draft.text)
         """
 
-    @forward_call(dialogs.edit_folder)
-    async def edit_folder(
-            self: 'TelegramClient',
-            entity: 'hints.EntitiesLike' = None,
-            folder: typing.Union[int, typing.Sequence[int]] = None,
-            *,
-            unpack=None
-    ) -> _tl.Updates:
-        """
-        Edits the folder used by one or more dialogs to archive them.
-
-        Arguments
-            entity (entities):
-                The entity or list of entities to move to the desired
-                archive folder.
-
-            folder (`int`):
-                The folder to which the dialog should be archived to.
-
-                If you want to "archive" a dialog, use ``folder=1``.
-
-                If you want to "un-archive" it, use ``folder=0``.
-
-                You may also pass a list with the same length as
-                `entities` if you want to control where each entity
-                will go.
-
-            unpack (`int`, optional):
-                If you want to unpack an archived folder, set this
-                parameter to the folder number that you want to
-                delete.
-
-                When you unpack a folder, all the dialogs inside are
-                moved to the folder number 0.
-
-                You can only use this parameter if the other two
-                are not set.
-
-        Returns
-            The :tl:`Updates` object that the request produces.
-
-        Example
-            .. code-block:: python
-
-                # Archiving the first 5 dialogs
-                dialogs = await client.get_dialogs(5)
-                await client.edit_folder(dialogs, 1)
-
-                # Un-archiving the third dialog (archiving to folder 0)
-                await client.edit_folder(dialog[2], 0)
-
-                # Moving the first dialog to folder 0 and the second to 1
-                dialogs = await client.get_dialogs(2)
-                await client.edit_folder(dialogs, [0, 1])
-
-                # Un-archiving all dialogs
-                await client.edit_folder(unpack=1)
-        """
-
     @forward_call(dialogs.delete_dialog)
     async def delete_dialog(
             self: 'TelegramClient',

telethon/types/_custom/dialog.py

@@ -20,9 +20,6 @@ class Dialog:
         folder_id (`folder_id`):
             The folder ID that this dialog belongs to.
 
-        archived (`bool`):
-            Whether this dialog is archived or not (``folder_id is None``).
-
         message (`Message <telethon.tl.custom.message.Message>`):
             The last message sent on this dialog. Note that this member
             will not be updated when new messages arrive, it's only set
@@ -79,7 +76,6 @@ class Dialog:
         self.dialog = dialog
         self.pinned = bool(dialog.pinned)
         self.folder_id = dialog.folder_id
-        self.archived = dialog.folder_id is not None
         self.message = message
         self.date = getattr(self.message, 'date', None)
 
@@ -122,33 +118,6 @@ class Dialog:
         # or it would raise `PEER_ID_INVALID`).
         await self._client.delete_dialog(self.entity, revoke=revoke)
 
-    async def archive(self, folder=1):
-        """
-        Archives (or un-archives) this dialog.
-
-        Args:
-            folder (`int`, optional):
-                The folder to which the dialog should be archived to.
-
-                If you want to "un-archive" it, use ``folder=0``.
-
-        Returns:
-            The :tl:`Updates` object that the request produces.
-
-        Example:
-
-            .. code-block:: python
-
-                # Archiving
-                dialog.archive()
-
-                # Un-archiving
-                dialog.archive(0)
-        """
-        return await self._client(_tl.fn.folders.EditPeerFolders([
-            _tl.InputFolderPeer(self.input_entity, folder_id=folder)
-        ]))
-
     def to_dict(self):
         return {
             '_': 'Dialog',