From fc0d9af76a38969c48fd70176b09cc13c1f2c4a5 Mon Sep 17 00:00:00 2001 From: KurimuzonAkuma Date: Thu, 7 Dec 2023 23:09:17 +0300 Subject: [PATCH] Update story methods description --- compiler/docs/compiler.py | 14 +++--- pyrogram/methods/stories/__init__.py | 4 +- pyrogram/methods/stories/can_send_story.py | 5 +- pyrogram/methods/stories/copy_story.py | 9 ++-- pyrogram/methods/stories/delete_stories.py | 4 +- pyrogram/methods/stories/edit_story.py | 49 +++++++++++++++---- pyrogram/methods/stories/export_story_link.py | 5 +- pyrogram/methods/stories/forward_story.py | 8 +-- pyrogram/methods/stories/get_all_stories.py | 2 +- ...et_peer_stories.py => get_chat_stories.py} | 12 ++--- .../methods/stories/get_pinned_stories.py | 6 +-- pyrogram/methods/stories/get_stories.py | 8 +-- .../methods/stories/get_stories_archive.py | 4 +- pyrogram/methods/stories/hide_stories.py | 2 +- .../methods/stories/increment_story_views.py | 3 +- pyrogram/methods/stories/pin_stories.py | 6 +-- pyrogram/methods/stories/read_stories.py | 3 +- pyrogram/methods/stories/send_story.py | 9 ++-- 18 files changed, 92 insertions(+), 61 deletions(-) rename pyrogram/methods/stories/{get_peer_stories.py => get_chat_stories.py} (87%) diff --git a/compiler/docs/compiler.py b/compiler/docs/compiler.py index ebf75959..75186890 100644 --- a/compiler/docs/compiler.py +++ b/compiler/docs/compiler.py @@ -347,20 +347,22 @@ def pyrogram_api(): """, stories=""" Stories + can_send_story + copy_story delete_stories edit_story export_story_link + forward_story get_all_stories + get_chat_stories + get_pinned_stories get_stories_archive + get_stories + hide_stories increment_story_views + pin_stories read_stories send_story - pin_stories - hide_stories - can_send_story - get_pinned_stories - copy_story - forward_story """, premium=""" Premium diff --git a/pyrogram/methods/stories/__init__.py b/pyrogram/methods/stories/__init__.py index c034cd37..9f50a968 100644 --- a/pyrogram/methods/stories/__init__.py +++ b/pyrogram/methods/stories/__init__.py @@ -23,7 +23,7 @@ from .edit_story import EditStory from .export_story_link import ExportStoryLink from .forward_story import ForwardStory from .get_all_stories import GetAllStories -from .get_peer_stories import GetPeerStories +from .get_chat_stories import GetChatStories from .get_pinned_stories import GetPinnedStories from .get_stories import GetStories from .get_stories_archive import GetStoriesArchive @@ -41,7 +41,7 @@ class Stories( ExportStoryLink, ForwardStory, GetAllStories, - GetPeerStories, + GetChatStories, GetPinnedStories, GetStories, GetStoriesArchive, diff --git a/pyrogram/methods/stories/can_send_story.py b/pyrogram/methods/stories/can_send_story.py index 61d1abe1..5a7c3399 100644 --- a/pyrogram/methods/stories/can_send_story.py +++ b/pyrogram/methods/stories/can_send_story.py @@ -16,11 +16,10 @@ # You should have received a copy of the GNU Lesser General Public License # along with Pyrogram. If not, see . -from typing import Union, Iterable +from typing import Union import pyrogram from pyrogram import raw -from pyrogram import types class CanSendStory: @@ -30,7 +29,7 @@ class CanSendStory: ) -> bool: """Can send story - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): diff --git a/pyrogram/methods/stories/copy_story.py b/pyrogram/methods/stories/copy_story.py index 63d21e5d..28eb6057 100644 --- a/pyrogram/methods/stories/copy_story.py +++ b/pyrogram/methods/stories/copy_story.py @@ -17,11 +17,10 @@ # along with Pyrogram. If not, see . import logging -from datetime import datetime from typing import Union, List, Optional import pyrogram -from pyrogram import types, enums, utils +from pyrogram import types, enums log = logging.getLogger(__name__) @@ -43,7 +42,7 @@ class CopyStory: ) -> "types.Story": """Copy story. - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): @@ -71,13 +70,13 @@ class CopyStory: Story privacy. Defaults to :obj:`~pyrogram.enums.StoriesPrivacyRules.PUBLIC` - allowed_users (List of ``int``, *optional*): + allowed_users (List of ``int`` | ``str``, *optional*): List of user_id or chat_id of chat users who are allowed to view stories. Note: chat_id available only with :obj:`~pyrogram.enums.StoriesPrivacyRules.SELECTED_USERS`. Works with :obj:`~pyrogram.enums.StoriesPrivacyRules.CLOSE_FRIENDS` and :obj:`~pyrogram.enums.StoriesPrivacyRules.SELECTED_USERS` only - disallowed_users (List of ``int``, *optional*): + disallowed_users (List of ``int`` | ``str``, *optional*): List of user_id whos disallow to view the stories. Note: Works with :obj:`~pyrogram.enums.StoriesPrivacyRules.PUBLIC` and :obj:`~pyrogram.enums.StoriesPrivacyRules.CONTACTS` only diff --git a/pyrogram/methods/stories/delete_stories.py b/pyrogram/methods/stories/delete_stories.py index c37892c7..87c29c15 100644 --- a/pyrogram/methods/stories/delete_stories.py +++ b/pyrogram/methods/stories/delete_stories.py @@ -31,7 +31,7 @@ class DeleteStories: ) -> List[int]: """Delete stories. - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): @@ -39,7 +39,7 @@ class DeleteStories: 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`` | ``list``): + story_ids (``int`` | Iterable of ``int``, *optional*): Unique identifier (int) or list of unique identifiers (list of int) for the target stories. Returns: diff --git a/pyrogram/methods/stories/edit_story.py b/pyrogram/methods/stories/edit_story.py index 868ef751..6b1cee19 100644 --- a/pyrogram/methods/stories/edit_story.py +++ b/pyrogram/methods/stories/edit_story.py @@ -17,7 +17,6 @@ # along with Pyrogram. If not, see . import os -import re from typing import List, Union, BinaryIO, Callable import pyrogram @@ -81,7 +80,6 @@ class EditStory: privacy (:obj:`~pyrogram.enums.StoriesPrivacyRules`, *optional*): Story privacy. - Defaults to :obj:`~pyrogram.enums.StoriesPrivacyRules.PUBLIC` allowed_users (List of ``int``, *optional*): List of user_id or chat_id of chat users who are allowed to view stories. @@ -118,20 +116,53 @@ class EditStory: Example: .. code-block:: python - # Send new photo story - photo_id = "abcd12345" - await app.edit_story(meida=photo_id, caption='Hello guys.') + # Edit story in your profile + await app.edit_story("me", "story.png", caption='My new story!') + + # Edit story in channel + await app.edit_story(123456, "story.png", caption='My new story!') Raises: ValueError: In case of invalid arguments. """ # TODO: media_areas - if privacy: - privacy_rules = [types.StoriesPrivacyRules(type=privacy)] - message, entities = (await utils.parse_text_entities(self, caption, parse_mode, caption_entities)).values() + privacy_rules = [] + + if privacy: + if privacy == enums.StoriesPrivacyRules.PUBLIC: + privacy_rules.append(raw.types.InputPrivacyValueAllowAll()) + if disallowed_users: + users = [await self.resolve_peer(user_id) for user_id in disallowed_users] + privacy_rules.append(raw.types.InputPrivacyValueDisallowUsers(users=users)) + elif privacy == enums.StoriesPrivacyRules.CONTACTS: + privacy_rules = [raw.types.InputPrivacyValueAllowContacts()] + if disallowed_users: + users = [await self.resolve_peer(user_id) for user_id in disallowed_users] + privacy_rules.append(raw.types.InputPrivacyValueDisallowUsers(users=users)) + elif privacy == enums.StoriesPrivacyRules.CLOSE_FRIENDS: + privacy_rules = [raw.types.InputPrivacyValueAllowCloseFriends()] + if allowed_users: + users = [await self.resolve_peer(user_id) for user_id in allowed_users] + privacy_rules.append(raw.types.InputPrivacyValueAllowUsers(users=users)) + elif privacy == enums.StoriesPrivacyRules.SELECTED_USERS: + _allowed_users = [] + _allowed_chats = [] + + for user in allowed_users: + peer = await self.resolve_peer(user) + if isinstance(peer, raw.types.InputPeerUser): + _allowed_users.append(peer) + elif isinstance(peer, raw.types.InputPeerChat): + _allowed_chats.append(peer) + + if _allowed_users: + privacy_rules.append(raw.types.InputPrivacyValueAllowUsers(users=_allowed_users)) + if _allowed_chats: + privacy_rules.append(raw.types.InputPrivacyValueAllowChatParticipants(chats=_allowed_chats)) + try: if isinstance(media, str): if os.path.isfile(media): @@ -208,7 +239,7 @@ class EditStory: peer = await self.resolve_peer(user) if isinstance(peer, raw.types.InputPeerUser): _allowed_users.append(peer) - elif isinstance(peer, raw.types.InputPeerChat): + elif isinstance(peer, (raw.types.InputPeerChat, raw.types.InputPeerChannel)): _allowed_chats.append(peer) if _allowed_users: diff --git a/pyrogram/methods/stories/export_story_link.py b/pyrogram/methods/stories/export_story_link.py index ac36c470..c7e48e81 100644 --- a/pyrogram/methods/stories/export_story_link.py +++ b/pyrogram/methods/stories/export_story_link.py @@ -20,7 +20,6 @@ from typing import Union import pyrogram from pyrogram import raw -from pyrogram import types class ExportStoryLink: @@ -28,10 +27,10 @@ class ExportStoryLink: self: "pyrogram.Client", chat_id: Union[int, str], story_id: int, - ) -> "types.ExportedStoryLink": + ) -> str: """Export a story link. - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): diff --git a/pyrogram/methods/stories/forward_story.py b/pyrogram/methods/stories/forward_story.py index 933eb558..9bd6358c 100644 --- a/pyrogram/methods/stories/forward_story.py +++ b/pyrogram/methods/stories/forward_story.py @@ -36,7 +36,7 @@ class ForwardStory: ) -> Optional["types.Message"]: """Send story. - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): @@ -53,7 +53,7 @@ class ForwardStory: Unique identifier of story. disable_notification (``bool``, *optional*): - Sends the message silently. + Sends the message with story silently. Users will receive a notification with no sound. message_thread_id (``int``, *optional*): @@ -64,13 +64,13 @@ class ForwardStory: Date when the message will be automatically sent. Returns: - :obj:`~pyrogram.types.Message`: On success, the sent stoty message is returned. + :obj:`~pyrogram.types.Message`: On success, the sent story message is returned. Example: .. code-block:: python # Send your story to chat_id - await app.forward_story(chat_id, "me", 1) + await app.forward_story(to_chat, from_chat, 123) """ r = await self.invoke( raw.functions.messages.SendMedia( diff --git a/pyrogram/methods/stories/get_all_stories.py b/pyrogram/methods/stories/get_all_stories.py index 45e7636c..20c1b00e 100644 --- a/pyrogram/methods/stories/get_all_stories.py +++ b/pyrogram/methods/stories/get_all_stories.py @@ -16,7 +16,7 @@ # You should have received a copy of the GNU Lesser General Public License # along with Pyrogram. If not, see . -from typing import AsyncGenerator, Union, Optional +from typing import AsyncGenerator, Optional import pyrogram from pyrogram import raw diff --git a/pyrogram/methods/stories/get_peer_stories.py b/pyrogram/methods/stories/get_chat_stories.py similarity index 87% rename from pyrogram/methods/stories/get_peer_stories.py rename to pyrogram/methods/stories/get_chat_stories.py index 98d539af..1ea5d89c 100644 --- a/pyrogram/methods/stories/get_peer_stories.py +++ b/pyrogram/methods/stories/get_chat_stories.py @@ -16,19 +16,19 @@ # You should have received a copy of the GNU Lesser General Public License # along with Pyrogram. If not, see . -from typing import AsyncGenerator, Union, Optional +from typing import AsyncGenerator, Union import pyrogram from pyrogram import raw from pyrogram import types -class GetPeerStories: - async def get_peer_stories( +class GetChatStories: + async def get_chat_stories( self: "pyrogram.Client", chat_id: Union[int, str] ) -> AsyncGenerator["types.Story", None]: - """Get all active stories from an user by using user identifiers. + """Get all non expired stories from a chat by using chat identifier. .. include:: /_includes/usable-by/users.rst @@ -44,8 +44,8 @@ class GetPeerStories: Example: .. code-block:: python - # Get all active story from spesific user - async for story in app.get_peer_stories(chat_id): + # Get all non expired stories from spesific chat + async for story in app.get_chat_stories(chat_id): print(story) Raises: diff --git a/pyrogram/methods/stories/get_pinned_stories.py b/pyrogram/methods/stories/get_pinned_stories.py index a4413ab9..347bf98d 100644 --- a/pyrogram/methods/stories/get_pinned_stories.py +++ b/pyrogram/methods/stories/get_pinned_stories.py @@ -16,7 +16,7 @@ # You should have received a copy of the GNU Lesser General Public License # along with Pyrogram. If not, see . -from typing import AsyncGenerator, Union, Optional +from typing import AsyncGenerator, Union import pyrogram from pyrogram import raw @@ -31,7 +31,7 @@ class GetPinnedStories: offset_id: int = 0, limit: int = 0, ) -> AsyncGenerator["types.Story", None]: - """Get pinned stories stories. + """Get all pinned stories from a chat by using chat identifier. .. include:: /_includes/usable-by/users.rst @@ -54,7 +54,7 @@ class GetPinnedStories: .. code-block:: python # Get all pinned story - async for story in app.get_pinned_stories(): + async for story in app.get_pinned_stories(chat_id): print(story) """ current = 0 diff --git a/pyrogram/methods/stories/get_stories.py b/pyrogram/methods/stories/get_stories.py index 71232b55..40ae2922 100644 --- a/pyrogram/methods/stories/get_stories.py +++ b/pyrogram/methods/stories/get_stories.py @@ -29,9 +29,9 @@ class GetStories: chat_id: Union[int, str], story_ids: Union[int, Iterable[int]], ) -> "types.Stories": - """Get stories by id. + """Get one or more stories from a chat by using stories identifiers. - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): @@ -39,7 +39,7 @@ class GetStories: For your personal story 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 (List of ``int`` ``32-bit``): + story_ids (``int`` | Iterable of ``int``, *optional*): Pass a single story identifier or an iterable of story ids (as integers) to get the content of the story themselves. @@ -51,7 +51,7 @@ class GetStories: .. code-block:: python # Get stories by id - stories = await app.get_stories_by_id(chat_id, [1, 2, 3]) + stories = await app.get_stories(chat_id, [1, 2, 3]) for story in stories: print(story) diff --git a/pyrogram/methods/stories/get_stories_archive.py b/pyrogram/methods/stories/get_stories_archive.py index 6a84fe55..49c70ca3 100644 --- a/pyrogram/methods/stories/get_stories_archive.py +++ b/pyrogram/methods/stories/get_stories_archive.py @@ -16,7 +16,7 @@ # You should have received a copy of the GNU Lesser General Public License # along with Pyrogram. If not, see . -from typing import AsyncGenerator, Union, Optional +from typing import AsyncGenerator, Union import pyrogram from pyrogram import raw @@ -30,7 +30,7 @@ class GetStoriesArchive: limit: int = 0, offset_id: int = 0 ) -> AsyncGenerator["types.Story", None]: - """Get stories archive. + """Get all archived stories from a chat by using chat identifier. .. include:: /_includes/usable-by/users.rst diff --git a/pyrogram/methods/stories/hide_stories.py b/pyrogram/methods/stories/hide_stories.py index 15173c46..e8ec242b 100644 --- a/pyrogram/methods/stories/hide_stories.py +++ b/pyrogram/methods/stories/hide_stories.py @@ -30,7 +30,7 @@ class HideStories: ) -> bool: """Toggle peer stories hidden - .. include:: /_includes/usable-by/users-bots.rst + .. include:: /_includes/usable-by/users.rst Parameters: chat_id (``int`` | ``str``): diff --git a/pyrogram/methods/stories/increment_story_views.py b/pyrogram/methods/stories/increment_story_views.py index ad4a4a19..c0fa937c 100644 --- a/pyrogram/methods/stories/increment_story_views.py +++ b/pyrogram/methods/stories/increment_story_views.py @@ -30,12 +30,11 @@ class IncrementStoryViews: ) -> bool: """Increment story views. - .. include:: /_includes/usable-by/users-bots.rst + .. 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_id (``int``): diff --git a/pyrogram/methods/stories/pin_stories.py b/pyrogram/methods/stories/pin_stories.py index 115c9c2e..530352c8 100644 --- a/pyrogram/methods/stories/pin_stories.py +++ b/pyrogram/methods/stories/pin_stories.py @@ -30,16 +30,16 @@ class PinStories: stories_ids: Union[int, Iterable[int]], pinned: bool = False, ) -> List[int]: - """Toggle stories pinned. + """Pin one or more stories in a chat by using stories identifiers. - .. include:: /_includes/usable-by/users-bots.rst + .. 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". - stories_ids (List of ``int`` ``32-bit``): + stories_ids (``int`` | Iterable of ``int``, *optional*): List of unique identifiers of the target stories. pinned (``bool``): diff --git a/pyrogram/methods/stories/read_stories.py b/pyrogram/methods/stories/read_stories.py index eec4c1a0..e067e365 100644 --- a/pyrogram/methods/stories/read_stories.py +++ b/pyrogram/methods/stories/read_stories.py @@ -30,12 +30,11 @@ class ReadStories: ) -> List[int]: """Read stories. - .. include:: /_includes/usable-by/users-bots.rst + .. 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). max_id (``int``, *optional*): diff --git a/pyrogram/methods/stories/send_story.py b/pyrogram/methods/stories/send_story.py index 56f5c4ce..0dfe129d 100644 --- a/pyrogram/methods/stories/send_story.py +++ b/pyrogram/methods/stories/send_story.py @@ -131,8 +131,11 @@ class SendStory: Example: .. code-block:: python - # Send new story - await app.send_story(media=file_id, caption='Hello guys.') + # Post story to your profile + await app.send_story("me", "story.png", caption='My new story!') + + # Post story to channel + await app.send_story(123456, "story.png", caption='My new story!') Raises: ValueError: In case of invalid arguments. @@ -217,7 +220,7 @@ class SendStory: peer = await self.resolve_peer(user) if isinstance(peer, raw.types.InputPeerUser): _allowed_users.append(peer) - elif isinstance(peer, raw.types.InputPeerChat): + elif isinstance(peer, (raw.types.InputPeerChat, raw.types.InputPeerChannel)): _allowed_chats.append(peer) if _allowed_users: