Simplify the workflow with UpdateState exposing a single flag param

telethon/telegram_bare_client.py

@@ -58,8 +58,7 @@ class TelegramBareClient:
     def __init__(self, session, api_id, api_hash,
                  connection_mode=ConnectionMode.TCP_FULL,
                  proxy=None,
-                 enable_updates=False,
-                 active_updates_polling=False,
+                 process_updates=False,
                  timeout=timedelta(seconds=5)):
         """Initializes the Telegram client with the specified API ID and Hash.
            Session must always be a Session instance, and an optional proxy
@@ -80,7 +79,7 @@ class TelegramBareClient:
 
         # This member will process updates if enabled.
         # One may change self.updates.enabled at any later point.
-        self.updates = UpdateState(enable_updates, active_updates_polling)
+        self.updates = UpdateState(process_updates)
 
         # These will be set later
         self.dc_options = None

telethon/telegram_client.py

@@ -57,8 +57,7 @@ class TelegramClient(TelegramBareClient):
     def __init__(self, session, api_id, api_hash,
                  connection_mode=ConnectionMode.TCP_FULL,
                  proxy=None,
-                 enable_updates=False,
-                 active_updates_polling=False,
+                 process_updates=False,
                  timeout=timedelta(seconds=5),
                  **kwargs):
         """Initializes the Telegram client with the specified API ID and Hash.
@@ -72,18 +71,15 @@ class TelegramClient(TelegramBareClient):
            This will only affect how messages are sent over the network
            and how much processing is required before sending them.
 
-           If 'enable_updates' is set to True, it will process incoming
-           updates to ensure that no duplicates are received, and update
-           handlers will be invoked. You CANNOT invoke requests from within
-           these handlers.
+           If 'process_updates' is set to True, incoming updates will be
+           processed and you must manually call 'self.updates.poll()' from
+           another thread to retrieve the saved update objects, or your
+           memory will fill with these. You may modify the value of
+           'self.updates.polling' at any later point.
 
-           In order to invoke requests upon receiving an update, you must
-           have your own thread (or use the main thread) and enable set
-           'active_updates_polling' to True. You must call self.updates.poll()
-           or you'll memory will be filled with unhandled updates.
-
-           You can also modify 'self.updates.enabled' and
-           'self.updates.set_polling()' at any later point.
+           Despite the value of 'process_updates', if you later call
+           '.add_update_handler(...)', updates will also be processed
+           and the update objects will be passed to the handlers you added.
 
            If more named arguments are provided as **kwargs, they will be
            used to update the Session instance. Most common settings are:
@@ -110,8 +106,7 @@ class TelegramClient(TelegramBareClient):
             session, api_id, api_hash,
             connection_mode=connection_mode,
             proxy=proxy,
-            enable_updates=enable_updates,
-            active_updates_polling=active_updates_polling,
+            process_updates=process_updates,
             timeout=timeout
         )
 
@@ -922,7 +917,10 @@ class TelegramClient(TelegramBareClient):
     def add_update_handler(self, handler):
         """Adds an update handler (a function which takes a TLObject,
           an update, as its parameter) and listens for updates"""
+        sync = not self.updates.handlers
         self.updates.handlers.append(handler)
+        if sync:
+            self.sync_updates()
 
     def remove_update_handler(self, handler):
         self.updates.handlers.remove(handler)

telethon/update_state.py

@@ -7,11 +7,10 @@ from .tl import types as tl
 
 class UpdateState:
     """Used to hold the current state of processed updates.
-       To retrieve an update, .pop_update() should be called.
+       To retrieve an update, .poll() should be called.
     """
-    def __init__(self, enabled, store_updates):
-        self.enabled = enabled
-        self._store_updates = store_updates
+    def __init__(self, polling):
+        self._polling = polling
         self.handlers = []
         self._updates_lock = RLock()
         self._updates_available = Event()
@@ -20,14 +19,14 @@ class UpdateState:
         # https://core.telegram.org/api/updates
         self._state = tl.updates.State(0, 0, datetime.now(), 0, 0)
 
-    def has_any(self):
-        """Returns True if a call to .pop_update() won't lock"""
+    def can_poll(self):
+        """Returns True if a call to .poll() won't lock"""
         return self._updates_available.is_set()
 
     def poll(self):
         """Polls an update or blocks until an update object is available"""
-        if not self._store_updates:
-            raise ValueError('Polling updates is not enabled.')
+        if not self._polling:
+            raise ValueError('Updates are not being polled hence not saved.')
 
         self._updates_available.wait()
         with self._updates_lock:
@@ -37,17 +36,22 @@ class UpdateState:
 
             return update
 
-    def set_polling(self, store):
-        self._store_updates = store
-        if not store:
+    def get_polling(self):
+        return self._polling
+
+    def set_polling(self, polling):
+        self._polling = polling
+        if not polling:
             with self._updates_lock:
                 self._updates.clear()
 
+    polling = property(fget=get_polling, fset=set_polling)
+
     def process(self, update):
         """Processes an update object. This method is normally called by
            the library itself.
         """
-        if not self.enabled:
+        if not self._polling or not self.handlers:
             return
 
         with self._updates_lock:
@@ -58,6 +62,6 @@ class UpdateState:
                 for handler in self.handlers:
                     handler(update)
 
-                if self._store_updates:
+                if self._polling:
                     self._updates.append(update)
                     self._updates_available.set()

telethon_examples/interactive_telegram_client.py

@@ -52,7 +52,6 @@ class InteractiveTelegramClient(TelegramClient):
         super().__init__(
             session_user_id, api_id, api_hash,
             connection_mode=ConnectionMode.TCP_ABRIDGED,
-            enable_updates=True,
             proxy=proxy
         )