From 51de0bd2da505d824e0b2cfac069dedbfeefda73 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Tue, 11 Jun 2019 11:09:22 +0200 Subject: [PATCH] Update documentation with intersphinx and better summaries --- readthedocs/basic/updates.rst | 4 +- readthedocs/concepts/asyncio.rst | 25 +-- readthedocs/concepts/updates.rst | 4 +- readthedocs/conf.py | 5 + readthedocs/examples/chats-and-channels.rst | 10 +- readthedocs/misc/changelog.rst | 6 +- .../misc/compatibility-and-convenience.rst | 16 +- .../quick-references/events-reference.rst | 210 ++++++++++-------- .../quick-references/objects-reference.rst | 3 +- telethon/client/auth.py | 5 +- telethon/events/callbackquery.py | 3 +- telethon/events/chataction.py | 2 +- telethon/events/inlinequery.py | 3 +- telethon/events/messagedeleted.py | 4 +- telethon/events/messageedited.py | 4 +- telethon/events/messageread.py | 2 +- telethon/events/newmessage.py | 2 +- telethon/events/raw.py | 4 +- telethon/events/userupdate.py | 5 +- 19 files changed, 174 insertions(+), 143 deletions(-) diff --git a/readthedocs/basic/updates.rst b/readthedocs/basic/updates.rst index 7e3a5e71..6e22ae64 100644 --- a/readthedocs/basic/updates.rst +++ b/readthedocs/basic/updates.rst @@ -79,7 +79,7 @@ with a ``'hi!'`` message. .. note:: Event handlers **must** be ``async def``. After all, - Telethon is an asynchronous library based on asyncio_, + Telethon is an asynchronous library based on `asyncio`, which is a safer and often faster approach to threads. You **must** ``await`` all method calls that use @@ -157,5 +157,3 @@ Make sure you understand the code seen here before continuing! As a rule of thumb, remember that new message events behave just like message objects, so you can do with them everything you can do with a message object. - -.. _asyncio: https://docs.python.org/3/library/asyncio.html diff --git a/readthedocs/concepts/asyncio.rst b/readthedocs/concepts/asyncio.rst index 182a5d6f..8500e55e 100644 --- a/readthedocs/concepts/asyncio.rst +++ b/readthedocs/concepts/asyncio.rst @@ -10,11 +10,11 @@ Mastering asyncio What's asyncio? =============== -asyncio_ is a Python 3's built-in library. This means it's already installed if +`asyncio` is a Python 3's built-in library. This means it's already installed if you have Python 3. Since Python 3.5, it is convenient to work with asynchronous code. Before (Python 3.4) we didn't have ``async`` or ``await``, but now we do. -asyncio_ stands for *Asynchronous Input Output*. This is a very powerful +`asyncio` stands for *Asynchronous Input Output*. This is a very powerful concept to use whenever you work IO. Interacting with the web or external APIs such as Telegram's makes a lot of sense this way. @@ -24,7 +24,7 @@ Why asyncio? Asynchronous IO makes a lot of sense in a library like Telethon. You send a request to the server (such as "get some message"), and -thanks to asyncio_, your code won't block while a response arrives. +thanks to `asyncio`, your code won't block while a response arrives. The alternative would be to spawn a thread for each update so that other code can run while the response arrives. That is *a lot* more @@ -234,7 +234,7 @@ the client: Generally, **you don't need threads** unless you know what you're doing. Just create another task, as shown above. If you're using the Telethon -with a library that uses threads, you must be careful to use ``threading.Lock`` +with a library that uses threads, you must be careful to use `threading.Lock` whenever you use the client, or enable the compatible mode. For that, see :ref:`compatibility-and-convenience`. @@ -254,7 +254,7 @@ client.run_until_disconnected() blocks! All of what `client.run_until_disconnected() ` does is -run the asyncio_'s event loop until the client is disconnected. That means +run the `asyncio`'s event loop until the client is disconnected. That means *the loop is running*. And if the loop is running, it will run all the tasks in it. So if you want to run *other* code, create tasks for it: @@ -274,9 +274,10 @@ in it. So if you want to run *other* code, create tasks for it: This creates a task for a clock that prints the time every second. You don't need to use `client.run_until_disconnected() ` either! -You just need to make the loop is running, somehow. ``asyncio.run_forever`` -and ``asyncio.run_until_complete`` can also be used to run the loop, and -Telethon will be happy with any approach. +You just need to make the loop is running, somehow. `loop.run_forever() +` and `loop.run_until_complete() +` can also be used to run +the loop, and Telethon will be happy with any approach. Of course, there are better tools to run code hourly or daily, see below. @@ -285,7 +286,7 @@ What else can asyncio do? ========================= Asynchronous IO is a really powerful tool, as we've seen. There are plenty -of other useful libraries that also use asyncio_ and that you can integrate +of other useful libraries that also use `asyncio` and that you can integrate with Telethon. * `aiohttp `_ is like the infamous @@ -314,7 +315,7 @@ you can run requests in parallel: This code will get the 10 last messages from `@TelethonChat `_, send one to `@TelethonOfftopic `_, and also download the profile -photo of the main group. asyncio_ will run all these three tasks +photo of the main group. `asyncio` will run all these three tasks at the same time. You can run all the tasks you want this way. A different way would be: @@ -355,8 +356,6 @@ Where can I read more? ====================== `Check out my blog post -`_ about asyncio_, which +`_ about `asyncio`, which has some more examples and pictures to help you understand what happens when the loop runs. - -.. _asyncio: https://docs.python.org/3/library/asyncio.html diff --git a/readthedocs/concepts/updates.rst b/readthedocs/concepts/updates.rst index aec75094..a5b978de 100644 --- a/readthedocs/concepts/updates.rst +++ b/readthedocs/concepts/updates.rst @@ -158,12 +158,12 @@ Understanding asyncio ===================== -With ``asyncio``, the library has several tasks running in the background. +With `asyncio`, the library has several tasks running in the background. One task is used for sending requests, another task is used to receive them, and a third one is used to handle updates. To handle updates, you must keep your script running. You can do this in -several ways. For instance, if you are *not* running ``asyncio``'s event +several ways. For instance, if you are *not* running `asyncio`'s event loop, you should use `client.run_until_disconnected `: diff --git a/readthedocs/conf.py b/readthedocs/conf.py index f7de1d4b..f4841dd5 100644 --- a/readthedocs/conf.py +++ b/readthedocs/conf.py @@ -40,9 +40,14 @@ tl_ref_url = 'https://tl.telethon.dev' extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', 'custom_roles' ] +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None) +} + # Change the default role so we can avoid prefixing everything with :obj: default_role = "py:obj" diff --git a/readthedocs/examples/chats-and-channels.rst b/readthedocs/examples/chats-and-channels.rst index 98bfdc07..fa485c59 100644 --- a/readthedocs/examples/chats-and-channels.rst +++ b/readthedocs/examples/chats-and-channels.rst @@ -195,11 +195,11 @@ banned rights of a user through :tl:`EditBannedRequest` and its parameter client(EditBannedRequest(channel, user, rights)) -You can also use a ``datetime`` object for ``until_date=``, or even a -Unix timestamp. Note that if you ban someone for less than 30 seconds -or for more than 366 days, Telegram will consider the ban to actually -last forever. This is officially documented under -https://core.telegram.org/bots/api#restrictchatmember. +You can use a `datetime.datetime` object for ``until_date=``, +a `datetime.timedelta` or even a Unix timestamp. Note that if you ban +someone for less than 30 seconds or for more than 366 days, Telegram +will consider the ban to actually last forever. This is officially +documented under https://core.telegram.org/bots/api#restrictchatmember. Kicking a member diff --git a/readthedocs/misc/changelog.rst b/readthedocs/misc/changelog.rst index 9a3b6074..44fc2b4b 100644 --- a/readthedocs/misc/changelog.rst +++ b/readthedocs/misc/changelog.rst @@ -1152,7 +1152,7 @@ reasons. But there's one more surprise! There is a new magic ``telethon.sync`` module to let you use **all** the methods in the :ref:`TelegramClient ` (and the types returned -from its functions) in a synchronous way, while using ``asyncio`` behind +from its functions) in a synchronous way, while using `asyncio` behind the scenes! This means you're now able to do both of the following: .. code-block:: python @@ -1238,7 +1238,7 @@ Bug fixes - "User joined" event was being treated as "User was invited". - SQLite's cursor should not be closed properly after usage. - ``await`` the updates task upon disconnection. -- Some bug in Python 3.5.2's ``asyncio`` causing 100% CPU load if you +- Some bug in Python 3.5.2's `asyncio` causing 100% CPU load if you forgot to call `client.disconnect() `. The method is called for you on object destruction, but you still should @@ -1373,7 +1373,7 @@ Enhancements - ``pathlib.Path`` is now supported for downloading and uploading media. - Messages you send to yourself are now considered outgoing, unless they are forwarded. -- The documentation has been updated with a brand new ``asyncio`` crash +- The documentation has been updated with a brand new `asyncio` crash course to encourage you use it. You can still use the threaded version if you want though. - ``.name`` property is now properly supported when sending and downloading diff --git a/readthedocs/misc/compatibility-and-convenience.rst b/readthedocs/misc/compatibility-and-convenience.rst index 9d6e8257..2d0769d4 100644 --- a/readthedocs/misc/compatibility-and-convenience.rst +++ b/readthedocs/misc/compatibility-and-convenience.rst @@ -4,7 +4,7 @@ Compatibility and Convenience ============================= -Telethon is an ``asyncio`` library. Compatibility is an important concern, +Telethon is an `asyncio` library. Compatibility is an important concern, and while it can't always be kept and mistakes happens, the :ref:`changelog` is there to tell you when these important changes happen. @@ -16,7 +16,7 @@ Compatibility Some decisions when developing will inevitable be proven wrong in the future. One of these decisions was using threads. Now that Python 3.4 is reaching EOL -and using ``asyncio`` is usable as of Python 3.5 it makes sense for a library +and using `asyncio` is usable as of Python 3.5 it makes sense for a library like Telethon to make a good use of it. If you have old code, **just use old versions** of the library! There is @@ -34,7 +34,7 @@ and clean-ups. Using an older version is the right way to go. Sometimes, other small decisions are made. These all will be reflected in the :ref:`changelog` which you should read when upgrading. -If you want to jump the ``asyncio`` boat, here are some of the things you will +If you want to jump the `asyncio` boat, here are some of the things you will need to start migrating really old code: .. code-block:: python @@ -91,7 +91,7 @@ Convenience This makes the examples shorter and easier to think about. For quick scripts that don't need updates, it's a lot more convenient to -forget about ``asyncio`` and just work with sequential code. This can prove +forget about `asyncio` and just work with sequential code. This can prove to be a powerful hybrid for running under the Python REPL too. .. code-block:: python @@ -178,10 +178,10 @@ overhead you pay if you import it, and what you save if you don't. Learning ======== -You know the library uses ``asyncio`` everywhere, and you want to learn -how to do things right. Even though ``asyncio`` is its own topic, the +You know the library uses `asyncio` everywhere, and you want to learn +how to do things right. Even though `asyncio` is its own topic, the documentation wants you to learn how to use Telethon correctly, and for -that, you need to use ``asyncio`` correctly too. For this reason, there +that, you need to use `asyncio` correctly too. For this reason, there is a section called :ref:`mastering-asyncio` that will introduce you to -the ``asyncio`` world, with links to more resources for learning how to +the `asyncio` world, with links to more resources for learning how to use it. Feel free to check that section out once you have read the rest. diff --git a/readthedocs/quick-references/events-reference.rst b/readthedocs/quick-references/events-reference.rst index ead94a15..cba224cd 100644 --- a/readthedocs/quick-references/events-reference.rst +++ b/readthedocs/quick-references/events-reference.rst @@ -19,34 +19,79 @@ its **attributes** (the properties will be shown here). .. contents:: -CallbackQuery +NewMessage +========== + +Occurs whenever a new text message or a message with media arrives. + +.. note:: + + The new message event **should be treated as** a + normal `Message `, with + the following exceptions: + + * ``pattern_match`` is the match object returned by ``pattern=``. + * ``message`` is **not** the message string. It's the `Message + ` object. + + Remember, this event is just a proxy over the message, so while + you won't see its attributes and properties, you can still access + them. Please see the full documentation for examples. + +Full documentation for the `NewMessage +`. + + +MessageEdited ============= -Full documentation for the `CallbackQuery -`. +Occurs whenever a message is edited. Just like `NewMessage +`, you should treat +this event as a `Message `. -.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event +Full documentation for the `MessageEdited +`. + + +MessageDeleted +============== + +Occurs whenever a message is deleted. Note that this event isn't 100% +reliable, since Telegram doesn't always notify the clients that a message +was deleted. + +It only has the ``deleted_id`` and ``deleted_ids`` attributes +(in addition to the chat if the deletion happened in a channel). + +Full documentation for the `MessageDeleted +`. + + +MessageRead +=========== + +Occurs whenever one or more messages are read in a chat. + +Full documentation for the `MessageRead +`. + +.. currentmodule:: telethon.events.messageread.MessageRead.Event .. autosummary:: :nosignatures: - id - message_id - data - chat_instance - via_inline + inbox + message_ids - respond - reply - edit - delete - answer - get_message + get_messages + is_read ChatAction ========== +Occurs whenever a user joins or leaves a chat, or a message is pinned. + Full documentation for the `ChatAction `. @@ -76,9 +121,63 @@ Full documentation for the `ChatAction get_input_users +UserUpdate +========== + +Occurs whenever a user goes online, starts typing, etc. + +A lot of fields are attributes and not properties, so they +are not shown here. Please refer to its full documentation. + +Full documentation for the `UserUpdate +`. + +.. currentmodule:: telethon.events.userupdate.UserUpdate.Event + +.. autosummary:: + :nosignatures: + + user + input_user + user_id + + get_user + get_input_user + + +CallbackQuery +============= + +Occurs whenever you sign in as a bot and a user +clicks one of the inline buttons on your messages. + +Full documentation for the `CallbackQuery +`. + +.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event + +.. autosummary:: + :nosignatures: + + id + message_id + data + chat_instance + via_inline + + respond + reply + edit + delete + answer + get_message + InlineQuery =========== +Occurs whenever you sign in as a bot and a user +sends an inline query such as ``@bot query``. + Full documentation for the `InlineQuery `. @@ -95,90 +194,9 @@ Full documentation for the `InlineQuery answer - -MessageDeleted -============== - -Full documentation for the `MessageDeleted -`. - -It only has the ``deleted_id`` and ``deleted_ids`` attributes -(in addition to the chat if the deletion happened in a channel). - - -MessageEdited -============= - -Full documentation for the `MessageEdited -`. - -This event is the same as `NewMessage -`, -but occurs only when an edit happens. - - -MessageRead -=========== - -Full documentation for the `MessageRead -`. - -.. currentmodule:: telethon.events.messageread.MessageRead.Event - -.. autosummary:: - :nosignatures: - - inbox - message_ids - - get_messages - is_read - - -NewMessage -========== - -Full documentation for the `NewMessage -`. - -Note that the new message event **should be treated as** a -normal `Message `, with -the following exceptions: - -* ``pattern_match`` is the match object returned by ``pattern=``. -* ``message`` is **not** the message string. It's the `Message - ` object. - -Remember, this event is just a proxy over the message, so while -you won't see its attributes and properties, you can still access -them. - - Raw === Raw events are not actual events. Instead, they are the raw :tl:`Update` object that Telegram sends. You normally shouldn't need these. - - -UserUpdate -========== - -Full documentation for the `UserUpdate -`. - -A lot of fields are attributes and not properties, so they -are not shown here. - -.. currentmodule:: telethon.events.userupdate.UserUpdate.Event - -.. autosummary:: - :nosignatures: - - user - input_user - user_id - - get_user - get_input_user diff --git a/readthedocs/quick-references/objects-reference.rst b/readthedocs/quick-references/objects-reference.rst index 4a09ff74..c8b2e876 100644 --- a/readthedocs/quick-references/objects-reference.rst +++ b/readthedocs/quick-references/objects-reference.rst @@ -249,7 +249,8 @@ InlineResult The `InlineResult ` object is returned inside a list by the `client.inline_query() ` method to make an inline -query to a bot that supports being used in inline mode, such as ``@like``. +query to a bot that supports being used in inline mode, such as +`@like `_. Note that the list returned is in fact a *subclass* of a list called `InlineResults `, which, diff --git a/telethon/client/auth.py b/telethon/client/auth.py index d7828d01..85654592 100644 --- a/telethon/client/auth.py +++ b/telethon/client/auth.py @@ -289,11 +289,12 @@ class AuthMethods(MessageParseMethods, UserMethods): password (`str`): 2FA password, should be used if a previous call raised - SessionPasswordNeededError. + ``SessionPasswordNeededError``. bot_token (`str`): Used to sign in as a bot. Not all requests will be available. - This should be the hash the @BotFather gave you. + This should be the hash the `@BotFather `_ + gave you. phone_code_hash (`str`, optional): The hash returned by `send_code_request`. This can be left as diff --git a/telethon/events/callbackquery.py b/telethon/events/callbackquery.py index e33fdf8f..99f0d147 100644 --- a/telethon/events/callbackquery.py +++ b/telethon/events/callbackquery.py @@ -10,7 +10,8 @@ from ..tl.custom.sendergetter import SenderGetter @name_inner_event class CallbackQuery(EventBuilder): """ - Represents a callback query event (when an inline button is clicked). + Occurs whenever you sign in as a bot and a user + clicks one of the inline buttons on your messages. Note that the `chats` parameter will **not** work with normal IDs or peers if the clicked inline button comes from a "via bot" diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index 6359cad6..75734e05 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -6,7 +6,7 @@ from ..tl import types, functions @name_inner_event class ChatAction(EventBuilder): """ - Represents an action in a chat (such as user joined, left, or new pin). + Occurs whenever a user joins or leaves a chat, or a message is pinned. """ @classmethod def build(cls, update): diff --git a/telethon/events/inlinequery.py b/telethon/events/inlinequery.py index 1ae3e00d..794ca857 100644 --- a/telethon/events/inlinequery.py +++ b/telethon/events/inlinequery.py @@ -12,7 +12,8 @@ from ..tl.custom.sendergetter import SenderGetter @name_inner_event class InlineQuery(EventBuilder): """ - Represents an inline query event (when someone writes ``'@my_bot query'``). + Occurs whenever you sign in as a bot and a user + sends an inline query such as ``@bot query``. Args: users (`entity`, optional): diff --git a/telethon/events/messagedeleted.py b/telethon/events/messagedeleted.py index 7312c163..dc86997d 100644 --- a/telethon/events/messagedeleted.py +++ b/telethon/events/messagedeleted.py @@ -5,7 +5,9 @@ from ..tl import types @name_inner_event class MessageDeleted(EventBuilder): """ - Event fired when one or more messages are deleted. + Occurs whenever a message is deleted. Note that this event isn't 100% + reliable, since Telegram doesn't always notify the clients that a message + was deleted. .. important:: diff --git a/telethon/events/messageedited.py b/telethon/events/messageedited.py index 6a8138a0..83a71dd6 100644 --- a/telethon/events/messageedited.py +++ b/telethon/events/messageedited.py @@ -6,7 +6,9 @@ from ..tl import types @name_inner_event class MessageEdited(NewMessage): """ - Event fired when a message has been edited. + Occurs whenever a message is edited. Just like `NewMessage + `, you should treat + this event as a `Message `. .. warning:: diff --git a/telethon/events/messageread.py b/telethon/events/messageread.py index 1b782db1..00ac6073 100644 --- a/telethon/events/messageread.py +++ b/telethon/events/messageread.py @@ -6,7 +6,7 @@ from ..tl import types @name_inner_event class MessageRead(EventBuilder): """ - Event fired when one or more messages have been read. + Occurs whenever one or more messages are read in a chat. Args: inbox (`bool`, optional): diff --git a/telethon/events/newmessage.py b/telethon/events/newmessage.py index 62d5deee..c1396f72 100644 --- a/telethon/events/newmessage.py +++ b/telethon/events/newmessage.py @@ -8,7 +8,7 @@ from ..tl import types @name_inner_event class NewMessage(EventBuilder): """ - Represents a new message event builder. + Occurs whenever a new text message or a message with media arrives. Args: incoming (`bool`, optional): diff --git a/telethon/events/raw.py b/telethon/events/raw.py index 4f25e769..cd4c80a9 100644 --- a/telethon/events/raw.py +++ b/telethon/events/raw.py @@ -4,7 +4,9 @@ from .. import utils class Raw(EventBuilder): """ - Represents a raw event. The event is the update itself. + Raw events are not actual events. Instead, they are the raw + :tl:`Update` object that Telegram sends. You normally shouldn't + need these. Args: types (`list` | `tuple` | `type`, optional): diff --git a/telethon/events/userupdate.py b/telethon/events/userupdate.py index 119af3d9..742c8034 100644 --- a/telethon/events/userupdate.py +++ b/telethon/events/userupdate.py @@ -9,7 +9,7 @@ from ..tl.custom.sendergetter import SenderGetter @name_inner_event class UserUpdate(EventBuilder): """ - Represents a user update (gone online, offline, joined Telegram). + Occurs whenever a user goes online, starts typing, etc. """ @classmethod def build(cls, update): @@ -32,7 +32,8 @@ class UserUpdate(EventBuilder): class Event(EventCommon, SenderGetter): """ - Represents the event of a user status update (last seen, joined). + Represents the event of a user update + such as gone online, started typing, etc. Members: online (`bool`, optional):