Update documentation, errors and add TODOs

readthedocs/extra/developing/api-status.rst

@@ -1,54 +0,0 @@
-.. _api-status:
-
-==========
-API Status
-==========
-
-
-In an attempt to help everyone who works with the Telegram API, the
-library will by default report all *Remote Procedure Call* errors to
-`RPC PWRTelegram <https://rpc.pwrtelegram.xyz/>`__, a public database
-anyone can query, made by `Daniil <https://github.com/danog>`__. All the
-information sent is a ``GET`` request with the error code, error message
-and method used.
-
-If you still would like to opt out, you can disable this feature by setting
-``client.session.report_errors = False``. However Daniil would really thank
-you if you helped him (and everyone) by keeping it on!
-
-Querying the API status
-***********************
-
-The API is accessed through ``GET`` requests, which can be made for
-instance through ``curl``. A JSON response will be returned.
-
-**All known errors and their description**:
-
-.. code:: bash
-
-    curl https://rpc.pwrtelegram.xyz/?all
-
-**Error codes for a specific request**:
-
-.. code:: bash
-
-    curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage
-
-**Number of** ``RPC_CALL_FAIL``:
-
-.. code:: bash
-
-    curl https://rpc.pwrtelegram.xyz/?rip  # last hour
-    curl https://rpc.pwrtelegram.xyz/?rip=$(time()-60)  # last minute
-
-**Description of errors**:
-
-.. code:: bash
-
-    curl https://rpc.pwrtelegram.xyz/?description_for=SESSION_REVOKED
-
-**Code of a specific error**:
-
-.. code:: bash
-
-    curl https://rpc.pwrtelegram.xyz/?code_for=STICKERSET_INVALID

readthedocs/extra/troubleshooting/rpc-errors.rst

@@ -9,7 +9,19 @@ something went wrong on Telegram's server). All the errors are
 available in :ref:`telethon-errors-package`, but some examples are:
 
 -  ``FloodWaitError`` (420), the same request was repeated many times.
-   Must wait ``.seconds`` (you can access this parameter).
+   Must wait ``.seconds`` (you can access this attribute). For example:
+
+   .. code-block:: python
+
+       ...
+       from telethon import errors
+
+       try:
+           print(client.get_messages(chat)[0].text)
+       except errors.FloodWaitError as e:
+           print('Have to sleep', e.seconds, 'seconds')
+           time.sleep(e.seconds)
+
 -  ``SessionPasswordNeededError``, if you have setup two-steps
    verification on Telegram.
 -  ``CdnFileTamperedError``, if the media you were trying to download
@@ -27,3 +39,7 @@ The generic classes for different error codes are:
 - ``NotFoundError`` (404), make sure you're invoking ``Request``\ 's!
 
 If the error is not recognised, it will only be an ``RPCError``.
+
+You can refer to all errors from Python through the ``telethon.errors``
+module. If you don't know what attributes they have, try printing their
+dir (like ``print(dir(e))``).

readthedocs/index.rst

@@ -90,7 +90,6 @@ heavy job for you, so you can focus on developing an application.
    :caption: Developing
 
    extra/developing/philosophy.rst
-   extra/developing/api-status.rst
    extra/developing/test-servers.rst
    extra/developing/project-structure.rst
    extra/developing/coding-style.rst

telethon/client/account.py

@@ -6,6 +6,8 @@ from .. import utils
 from ..tl import functions, TLRequest
 
 
+# TODO Make use of :tl:`InvokeWithMessagesRange` somehow
+#      For that, we need to use :tl:`GetSplitRanges` first.
 class _TakeoutClient:
     """
     Proxy object over the client.

telethon/client/telegrambaseclient.py

@@ -23,6 +23,7 @@ __default_log__ = logging.getLogger(__base_name__)
 __default_log__.addHandler(logging.NullHandler())
 
 
+# TODO How hard would it be to support both `trio` and `asyncio`?
 class TelegramBaseClient(abc.ABC):
     """
     This is the abstract base class for the client. It defines some

telethon_generator/data/errors.csv

@@ -93,6 +93,7 @@ FILEREF_UPGRADE_NEEDED,406,The file reference needs to be refreshed before being
 FIRSTNAME_INVALID,400,The first name is invalid
 FLOOD_TEST_PHONE_WAIT_X,420,A wait of {seconds} seconds is required in the test servers
 FLOOD_WAIT_X,420,A wait of {seconds} seconds is required
+FRESH_RESET_AUTHORISATION_FORBIDDEN,406,The current session is too new and cannot be used to reset other authorisations yet
 GIF_ID_INVALID,400,The provided GIF ID is invalid
 GROUPED_MEDIA_INVALID,400,Invalid grouped media
 HASH_INVALID,400,The provided hash is invalid