Multiple small changes/fixed typos to docs/error messages (#623)

readthedocs/extra/advanced-usage/update-modes.rst

@@ -37,7 +37,7 @@ an `Update`__ arrives:
         def callback(update):
             print('I received', update)
 
-        client.add_update_handler(callback)
+        client.add_event_handler(callback)
         # do more work here, or simply sleep!
 
 That's it! This is the old way to listen for raw updates, with no further
@@ -56,7 +56,7 @@ let's reply to them with the same text reversed:
                 client.send_message(PeerUser(update.user_id), update.message[::-1])
 
 
-        client.add_update_handler(replier)
+        client.add_event_handler(replier)
         input('Press enter to stop this!')
         client.disconnect()
 
@@ -96,9 +96,9 @@ additional workers:
 
     ``client = TelegramClient('session', api_id, api_hash, update_workers=0)``
 
-You **must** set it to ``0`` (or other number), as it defaults to ``None``
-and there is a different. ``None`` workers means updates won't be processed
-*at all*, so you must set it to some value (``0`` or greater) if you want
+You **must** set it to ``0`` (or higher), as it defaults to ``None`` and that
+has a different meaning. ``None`` workers means updates won't be processed
+*at all*, so you must set it to some integer value if you want
 ``client.updates.poll()`` to work.
 
 
@@ -134,7 +134,7 @@ As a complete example:
                                 update_workers=1, spawn_read_thread=False)
 
         client.connect()
-        client.add_update_handler(callback)
+        client.add_event_handler(callback)
         client.idle()  # ends with Ctrl+C
 
 

readthedocs/extra/basic/entities.rst

@@ -43,14 +43,15 @@ you're able to just do this:
         my_channel = client.get_entity(PeerChannel(some_id))
 
 
-All methods in the :ref:`telegram-client` call ``.get_input_entity()`` to
-further save you from the hassle of doing so manually, so doing things like
-``client.send_message('lonami', 'hi!')`` is possible.
+All methods in the :ref:`telegram-client` call ``.get_input_entity()`` prior
+to sending the requst to save you from the hassle of doing so manually.
+That way, convenience calls such as ``client.send_message('lonami', 'hi!')``
+become possible.
 
-Every entity the library "sees" (in any response to any call) will by
-default be cached in the ``.session`` file, to avoid performing
-unnecessary API calls. If the entity cannot be found, some calls
-like ``ResolveUsernameRequest`` or ``GetContactsRequest`` may be
+Every entity the library encounters (in any response to any call) will by
+default be cached in the ``.session`` file (an SQLite database), to avoid
+performing unnecessary API calls. If the entity cannot be found, additonal
+calls like ``ResolveUsernameRequest`` or ``GetContactsRequest`` may be
 made to obtain the required information.
 
 
@@ -61,16 +62,18 @@ Entities vs. Input Entities
 
     Don't worry if you don't understand this section, just remember some
     of the details listed here are important. When you're calling a method,
-    don't call ``.get_entity()`` before, just use the username or phone,
+    don't call ``.get_entity()`` beforehand, just use the username or phone,
     or the entity retrieved by other means like ``.get_dialogs()``.
 
 
-To save bandwidth, the API also makes use of their "input" versions.
-The input version of an entity (e.g. ``InputPeerUser``, ``InputChat``,
-etc.) only contains the minimum required information that's required
-for Telegram to be able to identify who you're referring to: their ID
-and hash. This ID/hash pair is unique per user, so if you use the pair
-given by another user **or bot** it will **not** work.
+On top of the normal types, the API also make use of what they call their
+``Input*`` versions of objects. The input version of an entity (e.g.
+``InputPeerUser``, ``InputChat``, etc.) only contains the minimum
+information that's required from Telegram to be able to identify
+who you're referring to: a ``Peer``'s **ID** and **hash**.
+
+This ID/hash pair is unique per user, so if you use the pair given by another
+user **or bot** it will **not** work.
 
 To save *even more* bandwidth, the API also makes use of the ``Peer``
 versions, which just have an ID. This serves to identify them, but

readthedocs/extra/basic/installation.rst

@@ -65,9 +65,10 @@ To generate the `method documentation`__, ``cd docs`` and then
 Optional dependencies
 *********************
 
-If ``libssl`` is available on your system, it will be used wherever encryption
-is needed, but otherwise it will fall back to pure Python implementation so it
-will also work without it.
+If the `cryptg`__ is installed, you might notice a speed-up in the download
+and upload speed, since these are the most cryptographic-heavy part of the
+library and said module is a C extension. Otherwise, the ``pyaes`` fallback
+will be used.
 
 
 __ https://github.com/ricmoo/pyaes
@@ -75,3 +76,4 @@ __ https://pypi.python.org/pypi/pyaes
 __ https://github.com/sybrenstuvel/python-rsa
 __ https://pypi.python.org/pypi/rsa/3.4.2
 __ https://lonamiwebs.github.io/Telethon
+__ https://github.com/Lonami/cryptg

readthedocs/extra/basic/working-with-updates.rst

@@ -10,6 +10,16 @@ over what Telegram calls `updates`__, and are meant to ease simple and common
 usage when dealing with them, since there are many updates. Let's dive in!
 
 
+.. note::
+
+    The library logs by default no output, and any exception that occurs
+    inside your handlers will be "hidden" from you to prevent the thread
+    from terminating (so it can still deliver events). You should enable
+    logging (``import logging; logging.basicConfig(level=logging.ERROR)``)
+    when working with events, at least the error level, to see if this is
+    happening so you can debug the error.
+
+
 .. contents::
 
 

readthedocs/extra/developing/telegram-api-in-other-languages.rst

@@ -18,6 +18,14 @@ there by `@vysheng <https://github.com/vysheng>`__,
 `telegram-cli <https://github.com/vysheng/tg>`__. Latest development
 has been moved to `BitBucket <https://bitbucket.org/vysheng/tdcli>`__.
 
+C++
+***
+
+The newest (and official) library, written from scratch, is called
+`tdlib <https://github.com/tdlib/td>`__ and is what the Telegram X
+uses. You can find more information in the official documentation,
+published `here <https://core.telegram.org/tdlib/docs/>`__.
+
 JavaScript
 **********
 
@@ -52,13 +60,14 @@ Python
 A fairly new (as of the end of 2017) Telegram library written from the
 ground up in Python by
 `@delivrance <https://github.com/delivrance>`__ and his
-`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library! No hard
-feelings Dan and good luck dealing with some of your users ;)
+`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library.
+There isn't really a reason to pick it over Telethon and it'd be kinda
+sad to see you go, but it would be nice to know what you miss from each
+other library in either one so both can improve.
 
 Rust
 ****
 
 Yet another work-in-progress implementation, this time for Rust thanks
 to `@JuanPotato <https://github.com/JuanPotato>`__ under the fancy
-name of `Vail <https://github.com/JuanPotato/Vail>`__. This one is very
-early still, but progress is being made at a steady rate.
+name of `Vail <https://github.com/JuanPotato/Vail>`__.

readthedocs/extra/examples/chats-and-channels.rst

@@ -121,6 +121,13 @@ a fixed limit:
             offset += len(participants.users)
 
 
+.. note::
+
+    It is **not** possible to get more than 10,000 members from a
+    group. It's a hard limit impossed by Telegram and there is
+    nothing you can do about it. Refer to `issue 573`__ for more.
+
+
 Note that ``GetParticipantsRequest`` returns `ChannelParticipants`__,
 which may have more information you need (like the role of the
 participants, total count of members, etc.)
@@ -130,6 +137,7 @@ __ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html
 __ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html
 __ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html
 __ https://lonamiwebs.github.io/Telethon/constructors/channels/channel_participants.html
+__ https://github.com/LonamiWebs/Telethon/issues/573
 
 
 Recent Actions

telethon/telegram_bare_client.py

@@ -455,7 +455,9 @@ class TelegramBareClient:
                 with self._reconnect_lock:
                     self._reconnect()
 
-        raise RuntimeError('Number of retries reached 0.')
+        raise RuntimeError('Number of retries reached 0 for {}.'.format(
+            [type(x).__name__ for x in requests]
+        ))
 
     # Let people use client.invoke(SomeRequest()) instead client(...)
     invoke = __call__

telethon/telegram_client.py

@@ -586,7 +586,7 @@ class TelegramClient(TelegramBareClient):
 
         Returns:
             A list of custom ``Draft`` objects that are easy to work with:
-            You can call :meth:`draft.set_message('text')` to change the message,
+            You can call ``draft.set_message('text')`` to change the message,
             or delete it through :meth:`draft.delete()`.
         """
         response = self(GetAllDraftsRequest())
@@ -2193,7 +2193,7 @@ class TelegramClient(TelegramBareClient):
                 return utils.get_input_peer(entity)
 
         raise TypeError(
-            'Could not find the input entity corresponding to "{}".'
+            'Could not find the input entity corresponding to "{}". '
             'Make sure you have encountered this peer before.'.format(peer)
         )
 

telethon/tl/custom/draft.py

@@ -42,7 +42,7 @@ class Draft:
         """
         Changes the draft message on the Telegram servers. The changes are
         reflected in this object. Changing only individual attributes like for
-        example the `reply_to_msg_id` should be done by providing the current
+        example the ``reply_to_msg_id`` should be done by providing the current
         values of this object, like so:
 
             draft.set_message(
@@ -56,7 +56,7 @@ class Draft:
         :param bool no_webpage: Whether to attach a web page preview
         :param int reply_to_msg_id: Message id to reply to
         :param list entities: A list of formatting entities
-        :return bool: `True` on success
+        :return bool: ``True`` on success
         """
         result = self._client(SaveDraftRequest(
             peer=self._peer,
@@ -77,6 +77,6 @@ class Draft:
     def delete(self):
         """
         Deletes this draft
-        :return bool: `True` on success
+        :return bool: ``True`` on success
         """
         return self.set_message(text='')

telethon/utils.py

@@ -35,8 +35,10 @@ VALID_USERNAME_RE = re.compile(r'^[a-zA-Z][\w\d]{3,30}[a-zA-Z\d]$')
 
 
 def get_display_name(entity):
-    """Gets the input peer for the given "entity" (user, chat or channel)
-       Returns None if it was not found"""
+    """
+    Gets the display name for the given entity, if it's an ``User``,
+    ``Chat`` or ``Channel``. Returns an empty string otherwise.
+    """
     if isinstance(entity, User):
         if entity.last_name and entity.first_name:
             return '{} {}'.format(entity.first_name, entity.last_name)