Change the way connection modes are specified

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 <https://github.com/LonamiWebs/Telethon/issues/1319>`__)
+anyway, so until there's a working solution, the mode is not supported. Pull Requests are welcome!
+
+
 The Conversation API has been removed
 -------------------------------------
 

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'
-]

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:

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,

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}')

telethon/enums.py

@@ -0,0 +1,3 @@
+from ._misc.enums import (
+    ConnectionMode,
+)