`opentele2.exception`

The opentele2 exception hierarchy and the mapping of core errors onto it.


from opentele2.exception import OpenTeleException, TDataBadDecryptKey, TFileNotFound

`OpenTeleException`

opentele2/exception.py


class OpenTeleException(BaseException):
    def __init__(self, message: str | None = None, stack_index: int = 1) -> None: ...
    message: str | None
    desc: str

The base of every opentele2 exception. str() gives the class name, the message and the caller, for example TFileNotFound: Could not open key_data [ Called by BaseObject.TDesktop.LoadTData() ].

OpenTeleException derives from BaseException, not Exception: an except Exception: clause does not catch it. Catch OpenTeleException or the subclass you expect.

Subclasses

Each subclass is raised as itself; the core error code is the code of the CoreError it is chained to, and the OT_ code of the same failure in Node.

Exception	Raised when
`TFileNotFound`	A required tdata file, such as the key file, does not exist. Core code: `TFILE_NOT_FOUND`.
`TDataInvalidMagic`	A tdata file does not start with `TDF$`, or the MTP data holds an unknown block. Core code: `TDATA_INVALID_MAGIC`.
`TDataInvalidCheckSum`	A tdata file’s MD5 checksum does not match its contents. Core code: `TDATA_INVALID_CHECKSUM`.
`TDataBadDecryptKey`	Decryption does not match its key: a passcode is missing or wrong. Core code: `TDATA_BAD_DECRYPT_KEY`.
`TDataWrongPasscode`	The local passcode does not unlock the folder. Core code: `TDATA_WRONG_PASSCODE`.
`TDataBadEncryptedDataSize`	Encrypted data has a size AES-IGE cannot take. Core code: `TDATA_BAD_ENCRYPTED_DATA_SIZE`.
`TDataBadDecryptedDataSize`	Decrypted data declares a size that does not fit. Core code: `TDATA_BAD_DECRYPTED_DATA_SIZE`.
`TDataBadConfigData`	An MTP config, endpoint or session does not parse, or the main DC has no usable endpoint. Core code: `TDATA_BAD_CONFIG_DATA`.
`QDataStreamFailed`	A Qt data stream read or write failed, or a `.session` file has another layout. Core code: `QDATASTREAM_FAILED`.
`TDataReadMapDataFailed`	An account’s `maps` file cannot be read. Core code: `TDATA_READ_MAP_DATA_FAILED`.
`TDataReadMapDataIncorrectPasscode`	An account’s map was read with a wrong passcode. Core code: `TDATA_READ_MAP_DATA_INCORRECT_PASSCODE`.
`TDataAuthKeyNotFound`	No auth key was found for the main DC. Core code: `TDATA_AUTH_KEY_NOT_FOUND`.
`MaxAccountLimit`	A folder already holds six accounts. Core code: `MAX_ACCOUNT_LIMIT`.
`TDataSaveFailed`	Writing the folder failed, for example with duplicate account indices. Core code: `TDATA_SAVE_FAILED`.
`TDataKeyDataInvalid`	The key file is malformed or its passcode wrap parameters are unusable. Core code: `TDATA_KEY_DATA_INVALID`.
`AccountAuthKeyNotFound`	Defined for an account without an auth key; no current code path raises it.
`TDesktopUnauthorized`	The tdata session is not authorised for `CreateNewSession`.
`TelethonUnauthorized`	A Telethon client is not authorised or its self user cannot be resolved.
`TDesktopNotLoaded`	A `TDesktop` was used before loading accounts.
`TDesktopHasNoAccount`	A `TDesktop` holds no account or no main account.
`TDAccountNotLoaded`	An `Account` was used before loading.
`NoPasswordProvided`	A QR login met 2FA without a password.
`PasswordIncorrect`	The 2FA password is wrong.
`LoginFlagInvalid`	A flag other than `UseCurrentSession` and `CreateNewSession` was passed.
`NoInstanceMatched`	An `APIData` without `api_id` or `api_hash`.
`SessionFileNotFound`	The `.session` or `.json` of a pair is missing.
`SessionFileInvalid`	A session has no auth key, or a `.json` companion is not a valid session JSON.

TDataKeyDataInvalid is outside __all__, so from opentele2.exception import * leaves it out; import it by name. TDataDcIdNotFound, raised by MtpConfigView.endpoints, lives in opentele2.td.mtp. A key file whose accounts info lists no account raises a plain OpenTeleException.

Core codes without a class of their own raise a builtin: BAD_LENGTH and INVALID_INPUT raise ValueError, IO raises OSError, and the SRP refusals SRP_BAD_PRIME_OR_GENERATOR, SRP_BAD_B, SRP_NO_GOOD_RANDOM and SRP_RANDOM_UNAVAILABLE raise ValueError.

Core errors

opentele2/exception.py


CORE_ERROR_TYPES: Mapping[str, type[BaseException]]
 
def raise_core_error(error: CoreError, stack_index: int = 1) -> typing.NoReturn: ...

Name	Description
`CORE_ERROR_TYPES`	The exception class raised for each `CoreError` code, from `_native.core_error_classes()`.
`raise_core_error(error)`	Raises `error` as its class in `CORE_ERROR_TYPES`, chained to it, with `error.legacy_message` as the message; an unknown code re-raises `error` itself.

CoreError is the exception of opentele2._native: code is the stable code, message the human-readable text, legacy_message the stable message of the matching class and detail_code the code of a context raised differently (BAD_ACCOUNTS_COUNT).

Helpers

opentele2/exception.py


def Expects(
    condition: bool,
    exception: OpenTeleException | str | None = None,
    done: Callable[[], None] | None = None,
    fail: Callable[[OpenTeleException], None] | None = None,
    silent: bool = False,
    stack_index: int = 1,
) -> bool: ...
 
def ExpectStreamStatus(stream: _DataStream, message: str = "Could not stream data") -> None: ...

Function	Description
`Expects(condition, exception, ...)`	Returns `condition` when it holds (calling `done`); otherwise raises `exception` (a string becomes an `OpenTeleException`), after calling `fail`. With `silent=True` it calls `fail` and returns `False` instead of raising.
`ExpectStreamStatus(stream, message)`	Raises `QDataStreamFailed` with `message` unless `stream.status()` is `0`.

errors.py


from opentele2.exception import OpenTeleException, TDataBadDecryptKey, TFileNotFound
from opentele2.td import TDesktop
 
try:
    tdesk = TDesktop("tdata")
except TFileNotFound:
    print("no key file in the folder")
except TDataBadDecryptKey:
    tdesk = TDesktop("tdata", passcode="local passcode")
except OpenTeleException as error:
    print(error)