From 72927a4ec3fffcb87d86529667113d1b8c9ab9b4 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Thu, 3 Jan 2019 19:23:28 +0100 Subject: [PATCH] Remove full API examples that have a friendly counterpart --- readthedocs/extra/examples/bots.rst | 73 -------------- .../extra/examples/chats-and-channels.rst | 75 --------------- .../extra/examples/working-with-messages.rst | 95 ------------------- readthedocs/index.rst | 1 - 4 files changed, 244 deletions(-) delete mode 100644 readthedocs/extra/examples/bots.rst diff --git a/readthedocs/extra/examples/bots.rst b/readthedocs/extra/examples/bots.rst deleted file mode 100644 index a3343c1b..00000000 --- a/readthedocs/extra/examples/bots.rst +++ /dev/null @@ -1,73 +0,0 @@ -==== -Bots -==== - - -.. note:: - - These examples assume you have read :ref:`accessing-the-full-api`. - -.. contents:: - - -Talking to Inline Bots -********************** - -You can query an inline bot, such as `@VoteBot`__ (note, *query*, -not *interact* with a voting message), by making use of the -:tl:`GetInlineBotResultsRequest` request: - -.. code-block:: python - - from telethon.tl.functions.messages import GetInlineBotResultsRequest - - bot_results = client(GetInlineBotResultsRequest( - bot, user_or_chat, 'query', '' - )) - -And you can select any of their results by using -:tl:`SendInlineBotResultRequest`: - -.. code-block:: python - - from telethon.tl.functions.messages import SendInlineBotResultRequest - - client(SendInlineBotResultRequest( - get_input_peer(user_or_chat), - obtained_query_id, - obtained_str_id - )) - - -Talking to Bots with special reply markup -***************************************** - -Generally, you just use the `message.click() -` method: - -.. code-block:: python - - messages = client.get_messages('somebot') - messages[0].click(0) - -You can also do it manually. - -To interact with a message that has a special reply markup, such as -`@VoteBot`__ polls, you would use :tl:`GetBotCallbackAnswerRequest`: - -.. code-block:: python - - from telethon.tl.functions.messages import GetBotCallbackAnswerRequest - - client(GetBotCallbackAnswerRequest( - user_or_chat, - msg.id, - data=msg.reply_markup.rows[wanted_row].buttons[wanted_button].data - )) - -It's a bit verbose, but it has all the information you would need to -show it visually (button rows, and buttons within each row, each with -its own data). - -__ https://t.me/vote -__ https://t.me/vote diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst index 12844c87..444e2c91 100644 --- a/readthedocs/extra/examples/chats-and-channels.rst +++ b/readthedocs/extra/examples/chats-and-channels.rst @@ -93,81 +93,6 @@ channel, you can use the :tl:`CheckChatInviteRequest`, which takes in the hash of said channel or group. -Retrieving all chat members (channels too) -****************************************** - -.. note:: - - Use the `telethon.telegram_client.TelegramClient.iter_participants` - friendly method instead unless you have a better reason not to! - - This method will handle different chat types for you automatically. - - -Here is the easy way to do it: - -.. code-block:: python - - participants = client.get_participants(group) - -Now we will show how the method works internally. - -In order to get all the members from a mega-group or channel, you need -to use :tl:`GetParticipantsRequest`. As we can see it needs an -:tl:`InputChannel`, (passing the mega-group or channel you're going to -use will work), and a mandatory :tl:`ChannelParticipantsFilter`. The -closest thing to "no filter" is to simply use -:tl:`ChannelParticipantsSearch` with an empty ``'q'`` string. - -If we want to get *all* the members, we need to use a moving offset and -a fixed limit: - -.. code-block:: python - - from telethon.tl.functions.channels import GetParticipantsRequest - from telethon.tl.types import ChannelParticipantsSearch - from time import sleep - - offset = 0 - limit = 100 - all_participants = [] - - while True: - participants = client(GetParticipantsRequest( - channel, ChannelParticipantsSearch(''), offset, limit, hash=0 - )) - if not participants.users: - break - all_participants.extend(participants.users) - offset += len(participants.users) - - -.. note:: - - If you need more than 10,000 members from a group you should use the - mentioned ``client.get_participants(..., aggressive=True)``. It will - do some tricks behind the scenes to get as many entities as possible. - Refer to `issue 573`__ for more on this. - - -Note that :tl:`GetParticipantsRequest` returns :tl:`ChannelParticipants`, -which may have more information you need (like the role of the -participants, total count of members, etc.) - -__ https://github.com/LonamiWebs/Telethon/issues/573 - - -Recent Actions -************** - -"Recent actions" is simply the name official applications have given to -the "admin log". Simply use :tl:`GetAdminLogRequest` for that, and -you'll get AdminLogResults.events in return which in turn has the final -`.action`__. - -__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html - - Admin Permissions ***************** diff --git a/readthedocs/extra/examples/working-with-messages.rst b/readthedocs/extra/examples/working-with-messages.rst index d574a6bb..08b47c8e 100644 --- a/readthedocs/extra/examples/working-with-messages.rst +++ b/readthedocs/extra/examples/working-with-messages.rst @@ -10,101 +10,6 @@ Working with messages .. contents:: -Forwarding messages -******************* - -.. note:: - - Use the `telethon.client.messages.MessageMethods.forward_messages` - friendly method instead unless you have a better reason not to! - - This method automatically accepts either a single message or many of them. - -.. code-block:: python - - # If you only have the message IDs - client.forward_messages( - entity, # to which entity you are forwarding the messages - message_ids, # the IDs of the messages (or message) to forward - from_entity # who sent the messages? - ) - - # If you have ``Message`` objects - client.forward_messages( - entity, # to which entity you are forwarding the messages - messages # the messages (or message) to forward - ) - - # You can also do it manually if you prefer - from telethon.tl.functions.messages import ForwardMessagesRequest - - messages = foo() # retrieve a few messages (or even one, in a list) - from_entity = bar() - to_entity = baz() - - client(ForwardMessagesRequest( - from_peer=from_entity, # who sent these messages? - id=[msg.id for msg in messages], # which are the messages? - to_peer=to_entity # who are we forwarding them to? - )) - -The named arguments are there for clarity, although they're not needed because -they appear in order. You can obviously just wrap a single message on the list -too, if that's all you have. - - -Searching Messages -******************* - -.. note:: - - Use the `telethon.client.messages.MessageMethods.iter_messages` - friendly method instead unless you have a better reason not to! - - This method has ``search`` and ``filter`` parameters that will - suit your needs. - -Messages are searched through the obvious :tl:`SearchRequest`, but you may run -into issues_. A valid example would be: - -.. code-block:: python - - from telethon.tl.functions.messages import SearchRequest - from telethon.tl.types import InputMessagesFilterEmpty - - filter = InputMessagesFilterEmpty() - result = client(SearchRequest( - peer=peer, # On which chat/conversation - q='query', # What to search for - filter=filter, # Filter to use (maybe filter for media) - min_date=None, # Minimum date - max_date=None, # Maximum date - offset_id=0, # ID of the message to use as offset - add_offset=0, # Additional offset - limit=10, # How many results - max_id=0, # Maximum message ID - min_id=0, # Minimum message ID - from_id=None, # Who must have sent the message (peer) - hash=0 # Special number to return nothing on no-change - )) - -It's important to note that the optional parameter ``from_id`` could have -been omitted (defaulting to ``None``). Changing it to :tl:`InputUserEmpty`, as one -could think to specify "no user", won't work because this parameter is a flag, -and it being unspecified has a different meaning. - -If one were to set ``from_id=InputUserEmpty()``, it would filter messages -from "empty" senders, which would likely match no users. - -If you get a ``ChatAdminRequiredError`` on a channel, it's probably because -you tried setting the ``from_id`` filter, and as the error says, you can't -do that. Leave it set to ``None`` and it should work. - -As with every method, make sure you use the right ID/hash combination for -your :tl:`InputUser` or :tl:`InputChat`, or you'll likely run into errors like -``UserIdInvalidError``. - - Sending stickers **************** diff --git a/readthedocs/index.rst b/readthedocs/index.rst index 236a9742..ad929f8d 100644 --- a/readthedocs/index.rst +++ b/readthedocs/index.rst @@ -69,7 +69,6 @@ heavy job for you, so you can focus on developing an application. extra/examples/working-with-messages extra/examples/chats-and-channels extra/examples/users - extra/examples/bots extra/examples/projects-using-telethon