diff --git a/client/doc/modules/types.rst b/client/doc/modules/types.rst index 56d1227e..75e3e33c 100644 --- a/client/doc/modules/types.rst +++ b/client/doc/modules/types.rst @@ -3,4 +3,67 @@ Types .. automodule:: telethon.types +Errors +------ + .. autoclass:: telethon.RpcError + +.. currentmodule:: telethon + +.. data:: errors + + Factory-object returning subclasses of :class:`RpcError`. + + You can think of it as a module with an infinite amount of error types in it. + + When accessing any attribute in this object, a subclass of :class:`RpcError` will be returned. + + The returned type will catch :class:`RpcError` if the :attr:`RpcError.name` matches the attribute converted to ``SCREAMING_CASE``. + + For example: + + .. code-block:: python + + from telethon import errors + + try: + await client.send_message(chat, text) + except errors.FloodWait as e: + await asyncio.sleep(e.value) + + The code above is equivalent to the following: + + .. code-block:: python + + from telethon import RpcError + + try: + await client.send_message(chat, text) + except RpcError as e: + if e.name == 'FLOOD_WAIT': + await asyncio.sleep(e.value) + else: + raise + + This factory object is merely a convenience. + + There is one exception, and that is when the attribute name starts with ``'Code'`` and ends with a number: + + .. code-block:: python + + try: + await client.send_message(chat, text) + except errors.Code420: + await asyncio.sleep(e.value) + + The above snippet is equivalent to checking :attr:`RpcError.code` instead: + + .. code-block:: python + + try: + await client.send_message(chat, text) + except RpcError as e: + if e.code == 420: + await asyncio.sleep(e.value) + else: + raise diff --git a/client/src/telethon/__init__.py b/client/src/telethon/__init__.py index 17333f8e..eaf37e9d 100644 --- a/client/src/telethon/__init__.py +++ b/client/src/telethon/__init__.py @@ -1,7 +1,8 @@ from ._impl import tl as _tl from ._impl.client import Client, Config +from ._impl.errors import errors from ._impl.mtproto import RpcError from ._impl.session import Session from .version import __version__ -__all__ = ["_tl", "Client", "Config", "RpcError", "Session"] +__all__ = ["_tl", "Client", "Config", "errors", "RpcError", "Session"] diff --git a/client/src/telethon/_impl/errors.py b/client/src/telethon/_impl/errors.py new file mode 100644 index 00000000..41e5b525 --- /dev/null +++ b/client/src/telethon/_impl/errors.py @@ -0,0 +1,8 @@ +class ErrorFactory: + __slots__ = () + + def __getattribute__(self, name: str) -> ValueError: + raise NotImplementedError + + +errors = ErrorFactory() diff --git a/client/src/telethon/_impl/mtproto/mtp/types.py b/client/src/telethon/_impl/mtproto/mtp/types.py index 31027df5..dde413ad 100644 --- a/client/src/telethon/_impl/mtproto/mtp/types.py +++ b/client/src/telethon/_impl/mtproto/mtp/types.py @@ -15,6 +15,8 @@ class RpcError(ValueError): Only occurs when the answer to a request sent to Telegram is not the expected result. The library will never construct instances of this error by itself. + This is the parent class of all :data:`telethon.errors` subtypes. + .. seealso:: :doc:`/concepts/errors`