From 71eb5426263932bf5f33862f338043e616f72d98 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sun, 26 Nov 2017 17:06:09 +0100 Subject: [PATCH] Document the errors/ module --- telethon/errors/__init__.py | 19 +++++++ telethon/errors/common.py | 29 ++++++++--- telethon/errors/rpc_base_errors.py | 79 ++++++++++++++++-------------- 3 files changed, 84 insertions(+), 43 deletions(-) diff --git a/telethon/errors/__init__.py b/telethon/errors/__init__.py index 6e62bfb9..fbb2f424 100644 --- a/telethon/errors/__init__.py +++ b/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, diff --git a/telethon/errors/common.py b/telethon/errors/common.py index be3b1d93..f2f21840 100644 --- a/telethon/errors/common.py +++ b/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.' diff --git a/telethon/errors/rpc_base_errors.py b/telethon/errors/rpc_base_errors.py index 5c938641..9e6eed1a 100644 --- a/telethon/errors/rpc_base_errors.py +++ b/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 - using a form and contains user generated data, the user should be - notified that the data must be corrected before the query is repeated. + The query contains errors. In the event that a request was created + using a form and contains user generated data, the user should be + 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 - to authorized users. + There was an unauthorized attempt to use functionality available only + 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 - someone who has blacklisted the current user. + Privacy violation. For example, an attempt to write a message to + 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 - 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 - phone number. + The maximum allowed number of attempts to invoke the given method + 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 + 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 - for example, there was a disruption while accessing a database or file - storage. + An internal server error occurred while a request was being processed + for example, there was a disruption while accessing a database or file + 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 ' - 'synchronize it using msg_id notifications and re-send the original message ' - 'with the "correct" msg_id or wrap it in a container with a new msg_id if the ' - 'original message had waited too long on the client to be transmitted).', + 'msg_id too low (most likely, client time is wrong it would be ' + 'worthwhile to synchronize it using msg_id notifications and re-send ' + 'the original message with the "correct" msg_id or wrap it in a ' + '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 ' - 'synchronized, and the message re-sent with the correct msg_id).', + 'msg_id too high (similar to the previous case, the client time has ' + '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 ' - 'to be divisible by 4).', + 'Incorrect two lower order msg_id bits (the server expects client ' + 'message msg_id to be divisible by 4).', 19: - 'Container msg_id is the same as msg_id of a previously received message ' - '(this must never happen).', + 'Container msg_id is the same as msg_id of a previously received ' + 'message (this must never happen).', 20: - 'Message too old, and it cannot be verified whether the server has received a ' - 'message with this msg_id or not.', + 'Message too old, and it cannot be verified whether the server has ' + '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_id but with either a higher or an equal and odd seqno).', + 'msg_seqno too low (the server has already received a message with a ' + '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 ' - 'either a lower or an equal and odd seqno).', + 'msg_seqno too high (similarly, there is a message with a higher ' + '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 ' - 'the correct salt, and the message is to be re-sent with it).', - 64: 'Invalid container.' + 'Incorrect server salt (in this case, the bad_server_salt response ' + 'is received with the correct salt, and the message is to be re-sent ' + 'with it).', + 64: + 'Invalid container.' } def __init__(self, code):