From 259bb6ace129cc3e46c8ca333340c992c785f497 Mon Sep 17 00:00:00 2001 From: Jeff Date: Sun, 8 Apr 2018 20:15:26 +0800 Subject: [PATCH] Several documentation fixes/additions (#750) --- README.rst | 2 +- readthedocs/extra/examples/bots.rst | 9 ++-- .../extra/examples/chats-and-channels.rst | 51 ++++++------------- .../extra/examples/working-with-messages.rst | 7 +-- telethon/events/chataction.py | 3 ++ 5 files changed, 24 insertions(+), 48 deletions(-) diff --git a/README.rst b/README.rst index a2e0d3de..6dee1cdd 100755 --- a/README.rst +++ b/README.rst @@ -52,7 +52,7 @@ Doing stuff client.send_file('username', '/home/myself/Pictures/holidays.jpg') client.download_profile_photo('me') - messages = client.get_message_history('username') + messages = client.get_messages('username') client.download_media(messages[0]) diff --git a/readthedocs/extra/examples/bots.rst b/readthedocs/extra/examples/bots.rst index fd4d54de..536d239a 100644 --- a/readthedocs/extra/examples/bots.rst +++ b/readthedocs/extra/examples/bots.rst @@ -13,7 +13,7 @@ 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 -`GetInlineBotResultsRequest`__ request: +:tl:`GetInlineBotResultsRequest` request: .. code-block:: python @@ -24,7 +24,7 @@ not *interact* with a voting message), by making use of the )) And you can select any of their results by using -`SendInlineBotResultRequest`__: +:tl:`SendInlineBotResultRequest`: .. code-block:: python @@ -41,7 +41,7 @@ Talking to Bots with special reply markup ***************************************** To interact with a message that has a special reply markup, such as -`@VoteBot`__ polls, you would use `GetBotCallbackAnswerRequest`__: +`@VoteBot`__ polls, you would use :tl:`GetBotCallbackAnswerRequest`: .. code-block:: python @@ -58,7 +58,4 @@ show it visually (button rows, and buttons within each row, each with its own data). __ https://t.me/vote -__ https://lonamiwebs.github.io/Telethon/methods/messages/get_inline_bot_results.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/send_inline_bot_result.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/get_bot_callback_answer.html __ https://t.me/vote diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst index 4465bb70..f59277a7 100644 --- a/readthedocs/extra/examples/chats-and-channels.rst +++ b/readthedocs/extra/examples/chats-and-channels.rst @@ -20,7 +20,7 @@ Joining a public channel ************************ Once you have the :ref:`entity ` of the channel you want to join -to, you can make use of the `JoinChannelRequest`__ to join such channel: +to, you can make use of the :tl:`JoinChannelRequest` to join such channel: .. code-block:: python @@ -35,7 +35,6 @@ to, you can make use of the `JoinChannelRequest`__ to join such channel: For more on channels, check the `channels namespace`__. -__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html __ https://lonamiwebs.github.io/Telethon/methods/channels/index.html @@ -47,7 +46,7 @@ If all you have is a link like this one: enough information to join! The part after the ``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this example, is the ``hash`` of the chat or channel. Now you can use -`ImportChatInviteRequest`__ as follows: +:tl:`ImportChatInviteRequest` as follows: .. code-block:: python @@ -55,15 +54,12 @@ example, is the ``hash`` of the chat or channel. Now you can use updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg')) -__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html - - Adding someone else to such chat or channel ******************************************* If you don't want to add yourself, maybe because you're already in, -you can always add someone else with the `AddChatUserRequest`__, which -use is very straightforward, or `InviteToChannelRequest`__ for channels: +you can always add someone else with the :tl:`AddChatUserRequest`, which +use is very straightforward, or :tl:`InviteToChannelRequest` for channels: .. code-block:: python @@ -87,21 +83,14 @@ use is very straightforward, or `InviteToChannelRequest`__ for channels: )) -__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html -__ https://lonamiwebs.github.io/Telethon/methods/channels/invite_to_channel.html - - Checking a link without joining ******************************* If you don't need to join but rather check whether it's a group or a -channel, you can use the `CheckChatInviteRequest`__, which takes in +channel, you can use the :tl:`CheckChatInviteRequest`, which takes in the hash of said channel or group. -__ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html - - Retrieving all chat members (channels too) ****************************************** @@ -113,11 +102,11 @@ Most of the time you will just need ``client.get_participants(entity)``. This is what said method is doing behind the scenes as an example. In order to get all the members from a mega-group or channel, you need -to use `GetParticipantsRequest`__. As we can see it needs an -`InputChannel`__, (passing the mega-group or channel you're going to -use will work), and a mandatory `ChannelParticipantsFilter`__. The +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 -`ChannelParticipantsSearch`__ with an empty ``'q'`` string. +: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: @@ -151,34 +140,28 @@ a fixed limit: Refer to `issue 573`__ for more on this. -Note that ``GetParticipantsRequest`` returns `ChannelParticipants`__, +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://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html -__ https://lonamiwebs.github.io/Telethon/types/input_channel.html -__ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html -__ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html __ https://github.com/LonamiWebs/Telethon/issues/573 -__ https://lonamiwebs.github.io/Telethon/constructors/channels/channel_participants.html Recent Actions ************** "Recent actions" is simply the name official applications have given to -the "admin log". Simply use `GetAdminLogRequest`__ for that, and +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/methods/channels/get_admin_log.html __ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html Admin Permissions ***************** -Giving or revoking admin permissions can be done with the `EditAdminRequest`__: +Giving or revoking admin permissions can be done with the :tl:`EditAdminRequest`: .. code-block:: python @@ -231,8 +214,8 @@ Restricting Users ***************** Similar to how you give or revoke admin permissions, you can edit the -banned rights of an user through `EditAdminRequest`__ and its parameter -`ChannelBannedRights`__: +banned rights of an user through :tl:`EditAdminRequest` and its parameter +:tl:`ChannelBannedRights`: .. code-block:: python @@ -289,12 +272,9 @@ is enough: ))) -__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_admin.html __ https://github.com/Kyle2142 __ https://github.com/LonamiWebs/Telethon/issues/490 __ https://lonamiwebs.github.io/Telethon/constructors/channel_admin_rights.html -__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_banned.html -__ https://lonamiwebs.github.io/Telethon/constructors/channel_banned_rights.html Increasing View Count in a Channel @@ -302,7 +282,7 @@ Increasing View Count in a Channel It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and while I don't understand why so many people ask this, the solution is to -use `GetMessagesViewsRequest`__, setting ``increment=True``: +use :tl:`GetMessagesViewsRequest`, setting ``increment=True``: .. code-block:: python @@ -326,4 +306,3 @@ __ https://github.com/LonamiWebs/Telethon/issues/233 __ https://github.com/LonamiWebs/Telethon/issues/305 __ https://github.com/LonamiWebs/Telethon/issues/409 __ https://github.com/LonamiWebs/Telethon/issues/447 -__ https://lonamiwebs.github.io/Telethon/methods/messages/get_messages_views.html diff --git a/readthedocs/extra/examples/working-with-messages.rst b/readthedocs/extra/examples/working-with-messages.rst index 3db1aed0..36abdf0d 100644 --- a/readthedocs/extra/examples/working-with-messages.rst +++ b/readthedocs/extra/examples/working-with-messages.rst @@ -51,7 +51,7 @@ too, if that's all you have. Searching Messages ******************* -Messages are searched through the obvious SearchRequest_, but you may run +Messages are searched through the obvious :tl:`SearchRequest`, but you may run into issues_. A valid example would be: .. code-block:: python @@ -75,7 +75,7 @@ into issues_. A valid example would be: )) It's important to note that the optional parameter ``from_id`` could have -been omitted (defaulting to ``None``). Changing it to InputUserEmpty_, as one +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. @@ -128,7 +128,4 @@ send yourself the very first sticker you have: )) -.. _ForwardMessagesRequest: https://lonamiwebs.github.io/Telethon/methods/messages/forward_messages.html -.. _SearchRequest: https://lonamiwebs.github.io/Telethon/methods/messages/search.html .. _issues: https://github.com/LonamiWebs/Telethon/issues/215 -.. _InputUserEmpty: https://lonamiwebs.github.io/Telethon/constructors/input_user_empty.html diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index 1a67394b..9f65a920 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -83,6 +83,9 @@ class ChatAction(EventBuilder): Represents the event of a new chat action. Members: + action_message (`MessageAction `_): + The message invoked by this Chat Action. + new_pin (`bool`): ``True`` if there is a new pin.