Refactor stories methods

compiler/docs/compiler.py

@@ -408,7 +408,7 @@ def get_title_list(s: str) -> list:
         """,
         stories="""
         Stories
-            can_send_story
+            can_post_stories
             copy_story
             delete_stories
             edit_story_caption
@@ -418,12 +418,14 @@ def get_title_list(s: str) -> list:
             get_all_stories
             get_chat_stories
             get_pinned_stories
-            get_stories_archive
+            get_archived_stories
             get_stories
-            hide_stories
+            hide_chat_stories
+            show_chat_stories
             view_stories
-            pin_stories
-            read_stories
+            pin_chat_stories
+            unpin_chat_stories
+            read_chat_stories
             send_story
         """,
         premium="""
@@ -795,6 +797,7 @@ def get_title_list(s: str) -> list:
         """,
         story="""
         Story
+            Story.reply
             Story.reply_text
             Story.reply_animation
             Story.reply_audio

pyrogram/methods/stories/__init__.py

@@ -16,41 +16,45 @@
 #  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 .can_send_story import CanSendStory
+from .can_post_stories import CanPostStories
 from .copy_story import CopyStory
 from .delete_stories import DeleteStories
 from .edit_story_caption import EditStoryCaption
 from .edit_story_media import EditStoryMedia
 from .edit_story_privacy import EditStoryPrivacy
 from .forward_story import ForwardStory
 from .get_all_stories import GetAllStories
+from .get_archived_stories import GetArchivedStories
 from .get_chat_stories import GetChatStories
 from .get_pinned_stories import GetPinnedStories
 from .get_stories import GetStories
-from .get_stories_archive import GetStoriesArchive
-from .hide_stories import HideStories
-from .view_stories import ViewStories
-from .pin_stories import PinStories
-from .read_stories import ReadStories
+from .hide_chat_stories import HideChatStories
+from .pin_chat_stories import PinChatStories
+from .read_chat_stories import ReadChatStories
 from .send_story import SendStory
+from .show_chat_stories import ShowChatStories
+from .unpin_chat_stories import UnpinChatStories
+from .view_stories import ViewStories
 
 class Stories(
-    CanSendStory,
+    CanPostStories,
     CopyStory,
     DeleteStories,
     EditStoryCaption,
     EditStoryMedia,
     EditStoryPrivacy,
     ForwardStory,
     GetAllStories,
+    GetArchivedStories,
     GetChatStories,
     GetPinnedStories,
     GetStories,
-    GetStoriesArchive,
-    HideStories,
-    ViewStories,
-    PinStories,
-    ReadStories,
+    HideChatStories,
+    PinChatStories,
+    ReadChatStories,
     SendStory,
+    ShowChatStories,
+    UnpinChatStories,
+    ViewStories,
 ):
     pass

pyrogram/methods/stories/can_send_story.py → pyrogram/methods/stories/can_post_stories.py

@@ -22,12 +22,12 @@
 from pyrogram import raw
 
 
-class CanSendStory:
-    async def can_send_story(
+class CanPostStories:
+    async def can_post_stories(
         self: "pyrogram.Client",
         chat_id: Union[int, str],
     ) -> bool:
-        """Can send story
+        """Check whether we can post stories as the specified chat.
 
         .. include:: /_includes/usable-by/users.rst
 
@@ -36,13 +36,13 @@ async def can_send_story(
                 Unique identifier (int) or username (str) of the target chat.
 
         Returns:
-            ``str``: On success, a bool is returned.
+            ``bool``: On success, True is returned.
 
         Example:
             .. code-block:: python
 
                 # Check if you can send story to chat id
-                app.can_send_story(chat_id)
+                app.can_post_stories(chat_id)
         """
         r = await self.invoke(
             raw.functions.stories.CanSendStory(

pyrogram/methods/stories/delete_stories.py

@@ -29,21 +29,20 @@ async def delete_stories(
         chat_id: Union[int, str],
         story_ids: Union[int, Iterable[int]],
     ) -> List[int]:
-        """Delete stories.
+        """Delete posted stories.
 
         .. include:: /_includes/usable-by/users.rst
 
         Parameters:
             chat_id (``int`` | ``str``):
                 Unique identifier (int) or username (str) of the target chat.
                 For your personal cloud (Saved Messages) you can simply use "me" or "self".
-                For a contact that exists in your Telegram address book you can use his phone number (str).
 
             story_ids (``int`` | Iterable of ``int``, *optional*):
                 Unique identifier (int) or list of unique identifiers (list of int) for the target stories.
 
         Returns:
-            List of ``int``: List of deleted stories IDs
+            List of ``int``: List of deleted stories IDs.
 
         Example:
             .. code-block:: python

pyrogram/methods/stories/forward_story.py

@@ -34,7 +34,7 @@ async def forward_story(
         message_thread_id: int = None,
         schedule_date: datetime = None,
     ) -> Optional["types.Message"]:
-        """Send story.
+        """Forward story.
 
         .. include:: /_includes/usable-by/users.rst
 

pyrogram/methods/stories/get_all_stories.py

@@ -30,10 +30,24 @@ async def get_all_stories(
         hidden: Optional[bool] = None,
         state: Optional[str] = None,
     ) -> AsyncGenerator["types.Story", None]:
-        """Get all active stories.
+        """Get all active (or hidden stories that displayed on the action bar on the homescreen.
 
         .. include:: /_includes/usable-by/users.rst
 
+        Parameters
+            next (``bool``, *optional*):
+                If next and state are both set, uses the passed state to paginate to the next results.
+                If neither state nor next are set, fetches the initial page.
+                If state is set and next is not set, check for changes in the active/hidden peerset.
+
+            hidden (``bool``, *optional*):
+                If set, fetches the hidden active story list, otherwise fetches the active story list.
+
+            state (``str``, *optional*):
+                If next and state are both set, uses the passed state to paginate to the next results.
+                If neither state nor next are set, fetches the initial page.
+                If state is set and next is not set, check for changes in the active/hidden peerset.
+
         Returns:
             ``Generator``: On success, a generator yielding :obj:`~pyrogram.types.Story` objects is returned.
 
@@ -43,9 +57,6 @@ async def get_all_stories(
                 # Get all active story
                 async for story in app.get_all_stories():
                     print(story)
-
-        Raises:
-            ValueError: In case of invalid arguments.
         """
 
         r = await self.invoke(

pyrogram/methods/stories/get_stories_archive.py → pyrogram/methods/stories/get_archived_stories.py

@@ -23,8 +23,8 @@
 from pyrogram import types
 
 
-class GetStoriesArchive:
-    async def get_stories_archive(
+class GetArchivedStories:
+    async def get_archived_stories(
         self: "pyrogram.Client",
         chat_id: Union[int, str],
         limit: int = 0,
@@ -47,13 +47,13 @@ async def get_stories_archive(
             offset_id (``int``, *optional*):
                 Identifier of the first story to be returned.
 
-        Yields:
-            :obj:`~pyrogram.types.Story` objects.
+        Returns:
+            ``Generator``: A generator yielding :obj:`~pyrogram.types.Story` objects.
 
         Example:
             .. code-block:: python
 
-                # Get stories archive
+                # Get archived stories from specific chat
                 async for story in app.get_stories_archive(chat_id):
                     print(story)
         """

pyrogram/methods/stories/get_chat_stories.py

@@ -44,7 +44,7 @@ async def get_chat_stories(
         Example:
             .. code-block:: python
 
-                # Get all non expired stories from spesific chat
+                # Get all non expired stories from specific chat
                 async for story in app.get_chat_stories(chat_id):
                     print(story)
 

pyrogram/methods/stories/get_pinned_stories.py

@@ -47,8 +47,8 @@ async def get_pinned_stories(
                 Maximum amount of events to be returned.
                 By default, all events will be returned.
 
-        Yields:
-            :obj:`~pyrogram.types.Story` objects.
+        Returns:
+            ``Generator``: On success, a generator yielding :obj:`~pyrogram.types.Story` objects is returned.
 
         Example:
             .. code-block:: python

pyrogram/methods/stories/hide_chat_stories.py

@@ -0,0 +1,56 @@
+#  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 typing import Union
+
+import pyrogram
+from pyrogram import raw
+
+
+class HideChatStories:
+    async def hide_chat_stories(
+        self: "pyrogram.Client",
+        chat_id: Union[int, str],
+    ) -> bool:
+        """Hide the active stories of a user, preventing them from being displayed on the action bar on the homescreen.
+
+        .. include:: /_includes/usable-by/users.rst
+
+        Parameters:
+            chat_id (``int`` | ``str``):
+                Unique identifier (int) or username (str) of the target chat.
+                For your personal cloud (Saved Messages) you can simply use "me" or "self".
+                For a contact that exists in your Telegram address book you can use his phone number (str).
+
+        Returns:
+            ``bool``: On success, a bool is returned.
+
+        Example:
+            .. code-block:: python
+
+                # Hide stories from specific chat
+                app.hide_chat_stories(chat_id)
+        """
+        r = await self.invoke(
+            raw.functions.stories.TogglePeerStoriesHidden(
+                peer=await self.resolve_peer(chat_id),
+                hidden=True
+            )
+        )
+
+        return r

pyrogram/methods/stories/pin_stories.py → pyrogram/methods/stories/pin_chat_stories.py

@@ -23,12 +23,11 @@
 from pyrogram import types
 
 
-class PinStories:
-    async def pin_stories(
+class PinChatStories:
+    async def pin_chat_stories(
         self: "pyrogram.Client",
         chat_id: Union[int, str],
-        stories_ids: Union[int, Iterable[int]],
-        pinned: bool = False,
+        stories_ids: Union[int, Iterable[int]]
     ) -> List[int]:
         """Pin one or more stories in a chat by using stories identifiers.
 
@@ -42,17 +41,14 @@ async def pin_stories(
             stories_ids (``int`` | Iterable of ``int``, *optional*):
                 List of unique identifiers of the target stories.
 
-            pinned (``bool``):
-                If set to ``True``, the stories will be pinned.
-
         Returns:
             List of ``int``: List of pinned stories IDs
 
         Example:
             .. code-block:: python
 
                 # Pin a single story
-                await app.pin_stories(chat_id, 123456789, True)
+                await app.pin_chat_stories(chat_id, 123456789)
 
         """
         is_iterable = not isinstance(stories_ids, int)
@@ -62,7 +58,7 @@ async def pin_stories(
             raw.functions.stories.TogglePinned(
                 peer=await self.resolve_peer(chat_id),
                 id=stories_ids,
-                pinned=pinned
+                pinned=True
             )
         )
 

pyrogram/methods/stories/read_stories.py → pyrogram/methods/stories/read_chat_stories.py

@@ -22,13 +22,13 @@
 from pyrogram import raw, types
 
 
-class ReadStories:
-    async def read_stories(
+class ReadChatStories:
+    async def read_chat_stories(
         self: "pyrogram.Client",
         chat_id: Union[int, str],
         max_id: int = 0,
     ) -> List[int]:
-        """Read stories.
+        """Mark all stories up to a certain identifier as read, for a given chat.
 
         .. include:: /_includes/usable-by/users.rst
 
@@ -38,8 +38,9 @@ async def read_stories(
                 For a contact that exists in your Telegram address book you can use his phone number (str).
 
             max_id (``int``, *optional*):
-                The id of the last story you want to mark as read; all the stories before this one will be marked as
-                read as well. Defaults to 0 (mark every unread message as read).
+                The id of the last story you want to mark as read.
+                All the stories before this one will be marked as read as well.
+                Defaults to 0 (mark every unread message as read).
 
         Returns:
             List of ``int``: On success, a list of read stories is returned.
@@ -48,10 +49,10 @@ async def read_stories(
             .. code-block:: python
 
                 # Read all stories
-                await app.read_stories(chat_id)
+                await app.read_chat_stories(chat_id)
 
                 # Mark stories as read only up to the given story id
-                await app.read_stories(chat_id, 123)
+                await app.read_chat_stories(chat_id, 123)
         """
         r = await self.invoke(
             raw.functions.stories.ReadStories(

pyrogram/methods/stories/send_story.py

@@ -46,7 +46,7 @@ async def send_story(
         progress: Callable = None,
         progress_args: tuple = ()
     ) -> "types.Story":
-        """Send new story.
+        """Post new story.
 
         .. include:: /_includes/usable-by/users.rst