diff --git a/readthedocs/misc/v2-migration-guide.rst b/readthedocs/misc/v2-migration-guide.rst index 4276dec8..8bf6ae6a 100644 --- a/readthedocs/misc/v2-migration-guide.rst +++ b/readthedocs/misc/v2-migration-guide.rst @@ -231,6 +231,36 @@ If you still want the old behaviour, wrap the list inside another list: #+ +Changes on how to configure a different connection mode +------------------------------------------------------- + +The ``connection`` parameter of the ``TelegramClient`` now expects a string, and not a type. +The supported values are: + +* ``'full'`` +* ``'intermediate'`` +* ``'abridged'`` +* ``'obfuscated'`` +* ``'http'`` + +The value chosen by the library is left as an implementation detail which may change. However, +you can force a certain mode by explicitly configuring it. If you don't want to hardcode the +string, you can import these values from the new ``telethon.enums`` module: + +.. code-block:: python + + client = TelegramClient(..., connection='tcp') + + # or + + from telethon.enums import ConnectionMode + client = TelegramClient(..., connection=ConnectionMode.TCP) + +You may have noticed there's currently no alternative for ``TcpMTProxy``. This mode has been +broken for some time now (see `issue #1319 `__) +anyway, so until there's a working solution, the mode is not supported. Pull Requests are welcome! + + The Conversation API has been removed ------------------------------------- diff --git a/telethon/__init__.py b/telethon/__init__.py index edbd4126..a10dc90c 100644 --- a/telethon/__init__.py +++ b/telethon/__init__.py @@ -5,13 +5,6 @@ from ._misc import utils # depends on helpers and _tl from ._misc import hints # depends on types/custom from ._client.telegramclient import TelegramClient -from ._network import connection -from . import version, events, utils, errors +from . import version, events, utils, errors, enums __version__ = version.__version__ - -__all__ = [ - 'TelegramClient', 'Button', - 'types', 'functions', 'custom', 'errors', - 'events', 'utils', 'connection' -] diff --git a/telethon/_client/telegrambaseclient.py b/telethon/_client/telegrambaseclient.py index 35507edd..85c07057 100644 --- a/telethon/_client/telegrambaseclient.py +++ b/telethon/_client/telegrambaseclient.py @@ -9,8 +9,8 @@ import typing from .. import version, helpers, __name__ as __base_name__, _tl from .._crypto import rsa -from .._misc import markdown, entitycache, statecache -from .._network import MTProtoSender, Connection, ConnectionTcpFull, TcpMTProxy +from .._misc import markdown, entitycache, statecache, enums +from .._network import MTProtoSender, Connection, ConnectionTcpFull, connection as conns from ..sessions import Session, SQLiteSession, MemorySession DEFAULT_DC_ID = 2 @@ -191,10 +191,19 @@ def init( self._timeout = timeout self._auto_reconnect = auto_reconnect - assert isinstance(connection, type) - self._connection = connection - init_proxy = None if not issubclass(connection, TcpMTProxy) else \ - _tl.InputClientProxy(*connection.address_info(proxy)) + if connection == (): + # For now the current default remains TCP Full; may change to be "smart" if proxies are specified + connection = enums.ConnectionMode.FULL + + self._connection = { + enums.ConnectionMode.FULL: conns.ConnectionTcpFull, + enums.ConnectionMode.INTERMEDIATE: conns.ConnectionTcpIntermediate, + enums.ConnectionMode.ABRIDGED: conns.ConnectionTcpAbridged, + enums.ConnectionMode.OBFUSCATED: conns.ConnectionTcpObfuscated, + enums.ConnectionMode.HTTP: conns.ConnectionHttp, + }[enums.parse_conn_mode(connection)] + init_proxy = None if not issubclass(self._connection, conns.TcpMTProxy) else \ + _tl.InputClientProxy(*self._connection.address_info(proxy)) # Used on connection. Capture the variables in a lambda since # exporting clients need to create this InvokeWithLayer. @@ -334,7 +343,7 @@ async def disconnect(self: 'TelegramClient'): return await _disconnect_coro(self) def set_proxy(self: 'TelegramClient', proxy: typing.Union[tuple, dict]): - init_proxy = None if not issubclass(self._connection, TcpMTProxy) else \ + init_proxy = None if not issubclass(self._connection, conns.TcpMTProxy) else \ _tl.InputClientProxy(*self._connection.address_info(proxy)) self._init_request.proxy = init_proxy @@ -347,7 +356,7 @@ def set_proxy(self: 'TelegramClient', proxy: typing.Union[tuple, dict]): connection = getattr(self._sender, "_connection", None) if connection: - if isinstance(connection, TcpMTProxy): + if isinstance(connection, conns.TcpMTProxy): connection._ip = proxy[0] connection._port = proxy[1] else: diff --git a/telethon/_client/telegramclient.py b/telethon/_client/telegramclient.py index cb644dd2..796af317 100644 --- a/telethon/_client/telegramclient.py +++ b/telethon/_client/telegramclient.py @@ -12,6 +12,7 @@ from .. import helpers, version, _tl from ..types import _custom from .._network import ConnectionTcpFull from ..events.common import EventBuilder, EventCommon +from .._misc import enums class TelegramClient: @@ -37,9 +38,15 @@ class TelegramClient: api_hash (`str`): The API hash you obtained from https://my.telegram.org. - connection (`telethon.network.connection.common.Connection`, optional): - The connection instance to be used when creating a new connection - to the servers. It **must** be a type. + connection (`str`, optional): + The connection mode to be used when creating a new connection + to the servers. The available modes are: + + * ``'full'`` + * ``'intermediate'`` + * ``'abridged'`` + * ``'obfuscated'`` + * ``'http'`` Defaults to `telethon.network.connection.tcpfull.ConnectionTcpFull`. @@ -2768,7 +2775,7 @@ class TelegramClient: api_id: int, api_hash: str, *, - connection: 'typing.Type[Connection]' = ConnectionTcpFull, + connection: typing.Union[str, enums.ConnectionMode] = (), use_ipv6: bool = False, proxy: typing.Union[tuple, dict] = None, local_addr: typing.Union[str, tuple] = None, diff --git a/telethon/_misc/enums.py b/telethon/_misc/enums.py new file mode 100644 index 00000000..107bbc31 --- /dev/null +++ b/telethon/_misc/enums.py @@ -0,0 +1,22 @@ +from enum import Enum + + +class ConnectionMode(Enum): + FULL = 'full' + INTERMEDIATE = 'intermediate' + ABRIDGED = 'abridged' + OBFUSCATED = 'obfuscated' + HTTP = 'http' + + +def parse_conn_mode(mode): + if isinstance(mode, ConnectionMode): + return mode + elif isinstance(mode, str): + for cm in ConnectionMode: + if mode == cm.value: + return cm + + raise ValueError(f'unknown connection mode: {mode!r}') + else: + raise TypeError(f'not a valid connection mode: {type(mode).__name__!r}') diff --git a/telethon/enums.py b/telethon/enums.py new file mode 100644 index 00000000..42e588c0 --- /dev/null +++ b/telethon/enums.py @@ -0,0 +1,3 @@ +from ._misc.enums import ( + ConnectionMode, +)