Document the errors/ module

telethon/errors/__init__.py

@@ -1,3 +1,7 @@
+"""
+This module holds all the base and automatically generated errors that the
+Telegram API has. See telethon_generator/errors.json for more.
+"""
 import urllib.request
 import re
 from threading import Thread
@@ -13,6 +17,13 @@ from .rpc_error_list import *
 
 
 def report_error(code, message, report_method):
+    """
+    Reports an RPC error to pwrtelegram.
+
+    :param code: the integer code of the error (like 400).
+    :param message: the message representing the error.
+    :param report_method: the constructor ID of the function that caused it.
+    """
     try:
         # Ensure it's signed
         report_method = int.from_bytes(
@@ -30,6 +41,14 @@ def report_error(code, message, report_method):
 
 
 def rpc_message_to_error(code, message, report_method=None):
+    """
+    Converts a Telegram's RPC Error to a Python error.
+
+    :param code: the integer code of the error (like 400).
+    :param message: the message representing the error.
+    :param report_method: if present, the ID of the method that caused it.
+    :return: the RPCError as a Python exception that represents this error.
+    """
     if report_method is not None:
         Thread(
             target=report_error,

telethon/errors/common.py

@@ -2,20 +2,23 @@
 
 
 class ReadCancelledError(Exception):
-    """Occurs when a read operation was cancelled"""
+    """Occurs when a read operation was cancelled."""
     def __init__(self):
         super().__init__(self, 'The read operation was cancelled.')
 
 
 class InvalidParameterError(Exception):
-    """Occurs when an invalid parameter is given, for example,
+    """
-    when either A or B are required but none is given"""
+    Occurs when an invalid parameter is given, for example,
+    when either A or B are required but none is given.
+    """
 
 
 class TypeNotFoundError(Exception):
-    """Occurs when a type is not found, for example,
+    """
-    when trying to read a TLObject with an invalid constructor code"""
+    Occurs when a type is not found, for example,
-
+    when trying to read a TLObject with an invalid constructor code.
+    """
     def __init__(self, invalid_constructor_id):
         super().__init__(
             self, 'Could not find a matching Constructor ID for the TLObject '
@@ -27,6 +30,10 @@ class TypeNotFoundError(Exception):
 
 
 class InvalidChecksumError(Exception):
+    """
+    Occurs when using the TCP full mode and the checksum of a received
+    packet doesn't match the expected checksum.
+    """
     def __init__(self, checksum, valid_checksum):
         super().__init__(
             self,
@@ -39,6 +46,9 @@ class InvalidChecksumError(Exception):
 
 
 class BrokenAuthKeyError(Exception):
+    """
+    Occurs when the authorization key for a data center is not valid.
+    """
     def __init__(self):
         super().__init__(
             self,
@@ -47,6 +57,9 @@ class BrokenAuthKeyError(Exception):
 
 
 class SecurityError(Exception):
+    """
+    Generic security error, mostly used when generating a new AuthKey.
+    """
     def __init__(self, *args):
         if not args:
             args = ['A security check failed.']
@@ -54,6 +67,10 @@ class SecurityError(Exception):
 
 
 class CdnFileTamperedError(SecurityError):
+    """
+    Occurs when there's a hash mismatch between the decrypted CDN file
+    and its expected hash.
+    """
     def __init__(self):
         super().__init__(
             'The CDN file has been altered and its download cancelled.'

telethon/errors/rpc_base_errors.py

@@ -1,11 +1,12 @@
 class RPCError(Exception):
+    """Base class for all Remote Procedure Call errors."""
     code = None
     message = None
 
 
 class InvalidDCError(RPCError):
     """
-        The request must be repeated, but directed to a different data center.
+    The request must be repeated, but directed to a different data center.
     """
     code = 303
     message = 'ERROR_SEE_OTHER'
@@ -13,9 +14,9 @@ class InvalidDCError(RPCError):
 
 class BadRequestError(RPCError):
     """
-        The query contains errors. In the event that a request was created
+    The query contains errors. In the event that a request was created
-        using a form and contains user generated data, the user should be
+    using a form and contains user generated data, the user should be
-        notified that the data must be corrected before the query is repeated.
+    notified that the data must be corrected before the query is repeated.
     """
     code = 400
     message = 'BAD_REQUEST'
@@ -23,8 +24,8 @@ class BadRequestError(RPCError):
 
 class UnauthorizedError(RPCError):
     """
-        There was an unauthorized attempt to use functionality available only
+    There was an unauthorized attempt to use functionality available only
-        to authorized users.
+    to authorized users.
     """
     code = 401
     message = 'UNAUTHORIZED'
@@ -32,8 +33,8 @@ class UnauthorizedError(RPCError):
 
 class ForbiddenError(RPCError):
     """
-        Privacy violation. For example, an attempt to write a message to
+    Privacy violation. For example, an attempt to write a message to
-        someone who has blacklisted the current user.
+    someone who has blacklisted the current user.
     """
     code = 403
     message = 'FORBIDDEN'
@@ -45,7 +46,7 @@ class ForbiddenError(RPCError):
 
 class NotFoundError(RPCError):
     """
-        An attempt to invoke a non-existent object, such as a method.
+    An attempt to invoke a non-existent object, such as a method.
     """
     code = 404
     message = 'NOT_FOUND'
@@ -57,10 +58,10 @@ class NotFoundError(RPCError):
 
 class FloodError(RPCError):
     """
-        The maximum allowed number of attempts to invoke the given method
+    The maximum allowed number of attempts to invoke the given method
-        with the given input parameters has been exceeded. For example, in an
+    with the given input parameters has been exceeded. For example, in an
-        attempt to request a large number of text messages (SMS) for the same
+    attempt to request a large number of text messages (SMS) for the same
-        phone number.
+    phone number.
     """
     code = 420
     message = 'FLOOD'
@@ -68,9 +69,9 @@ class FloodError(RPCError):
 
 class ServerError(RPCError):
     """
-        An internal server error occurred while a request was being processed
+    An internal server error occurred while a request was being processed
-        for example, there was a disruption while accessing a database or file
+    for example, there was a disruption while accessing a database or file
-        storage.
+    storage.
     """
     code = 500
     message = 'INTERNAL'
@@ -81,38 +82,42 @@ class ServerError(RPCError):
 
 
 class BadMessageError(Exception):
-    """Occurs when handling a bad_message_notification"""
+    """Occurs when handling a bad_message_notification."""
     ErrorMessages = {
         16:
-        'msg_id too low (most likely, client time is wrong it would be worthwhile to '
+        'msg_id too low (most likely, client time is wrong it would be '
-        'synchronize it using msg_id notifications and re-send the original message '
+        'worthwhile to synchronize it using msg_id notifications and re-send '
-        'with the "correct" msg_id or wrap it in a container with a new msg_id if the '
+        'the original message with the "correct" msg_id or wrap it in a '
-        'original message had waited too long on the client to be transmitted).',
+        'container with a new msg_id if the original message had waited too '
+        'long on the client to be transmitted).',
         17:
-        'msg_id too high (similar to the previous case, the client time has to be '
+        'msg_id too high (similar to the previous case, the client time has '
-        'synchronized, and the message re-sent with the correct msg_id).',
+        'to be synchronized, and the message re-sent with the correct msg_id).',
         18:
-        'Incorrect two lower order msg_id bits (the server expects client message msg_id '
+        'Incorrect two lower order msg_id bits (the server expects client '
-        'to be divisible by 4).',
+        'message msg_id to be divisible by 4).',
         19:
-        'Container msg_id is the same as msg_id of a previously received message '
+        'Container msg_id is the same as msg_id of a previously received '
-        '(this must never happen).',
+        'message (this must never happen).',
         20:
-        'Message too old, and it cannot be verified whether the server has received a '
+        'Message too old, and it cannot be verified whether the server has '
-        'message with this msg_id or not.',
+        'received a message with this msg_id or not.',
         32:
-        'msg_seqno too low (the server has already received a message with a lower '
+        'msg_seqno too low (the server has already received a message with a '
-        'msg_id but with either a higher or an equal and odd seqno).',
+        'lower msg_id but with either a higher or an equal and odd seqno).',
         33:
-        'msg_seqno too high (similarly, there is a message with a higher msg_id but with '
+        'msg_seqno too high (similarly, there is a message with a higher '
-        'either a lower or an equal and odd seqno).',
+        'msg_id but with either a lower or an equal and odd seqno).',
         34:
         'An even msg_seqno expected (irrelevant message), but odd received.',
-        35: 'Odd msg_seqno expected (relevant message), but even received.',
+        35:
+        'Odd msg_seqno expected (relevant message), but even received.',
         48:
-        'Incorrect server salt (in this case, the bad_server_salt response is received with '
+        'Incorrect server salt (in this case, the bad_server_salt response '
-        'the correct salt, and the message is to be re-sent with it).',
+        'is received with the correct salt, and the message is to be re-sent '
-        64: 'Invalid container.'
+        'with it).',
+        64:
+        'Invalid container.'
     }
 
     def __init__(self, code):