diff --git a/readthedocs/extra/advanced-usage/update-modes.rst b/readthedocs/extra/advanced-usage/update-modes.rst index 83495ef7..942af9c9 100644 --- a/readthedocs/extra/advanced-usage/update-modes.rst +++ b/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 diff --git a/readthedocs/extra/basic/entities.rst b/readthedocs/extra/basic/entities.rst index 472942a7..b68a74d7 100644 --- a/readthedocs/extra/basic/entities.rst +++ b/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 diff --git a/readthedocs/extra/basic/installation.rst b/readthedocs/extra/basic/installation.rst index 0f812127..c00ea79c 100644 --- a/readthedocs/extra/basic/installation.rst +++ b/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 diff --git a/readthedocs/extra/basic/working-with-updates.rst b/readthedocs/extra/basic/working-with-updates.rst index df971d7b..652f6000 100644 --- a/readthedocs/extra/basic/working-with-updates.rst +++ b/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:: diff --git a/readthedocs/extra/developing/telegram-api-in-other-languages.rst b/readthedocs/extra/developing/telegram-api-in-other-languages.rst index 44e45d51..7637282e 100644 --- a/readthedocs/extra/developing/telegram-api-in-other-languages.rst +++ b/readthedocs/extra/developing/telegram-api-in-other-languages.rst @@ -18,6 +18,14 @@ there by `@vysheng `__, `telegram-cli `__. Latest development has been moved to `BitBucket `__. +C++ +*** + +The newest (and official) library, written from scratch, is called +`tdlib `__ and is what the Telegram X +uses. You can find more information in the official documentation, +published `here `__. + 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 `__ and his -`Pyrogram `__ library! No hard -feelings Dan and good luck dealing with some of your users ;) +`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 `__ under the fancy -name of `Vail `__. This one is very -early still, but progress is being made at a steady rate. +name of `Vail `__. diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst index 44ee6112..95fa1b1e 100644 --- a/readthedocs/extra/examples/chats-and-channels.rst +++ b/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 diff --git a/telethon/telegram_bare_client.py b/telethon/telegram_bare_client.py index 23fd4ee4..8a15476e 100644 --- a/telethon/telegram_bare_client.py +++ b/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__ diff --git a/telethon/telegram_client.py b/telethon/telegram_client.py index 73cdbfe9..6cd1d6eb 100644 --- a/telethon/telegram_client.py +++ b/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) ) diff --git a/telethon/tl/custom/draft.py b/telethon/tl/custom/draft.py index ae08403a..9b800d4c 100644 --- a/telethon/tl/custom/draft.py +++ b/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='') diff --git a/telethon/utils.py b/telethon/utils.py index 8f38563a..ed93bdfa 100644 --- a/telethon/utils.py +++ b/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)