class Updater: """ This class, which employs the :class:`telegram.ext.Dispatcher`, provides a frontend to :class:`telegram.Bot` to the programmer, so they can focus on coding the bot. Its purpose is to receive the updates from Telegram and to deliver them to said dispatcher. It also runs in a separate thread, so the user can interact with the bot, for example on the command line. The dispatcher supports handlers for different kinds of data: Updates from Telegram, basic text commands and even arbitrary types. The updater can be started as a polling service or, for production, use a webhook to receive updates. This is achieved using the WebhookServer and WebhookHandler classes. Attributes: bot (:class:`telegram.Bot`): The bot used with this Updater. user_sig_handler (:obj:`function`): Optional. Function to be called when a signal is received. update_queue (:obj:`Queue`): Queue for the updates. job_queue (:class:`telegram.ext.JobQueue`): Jobqueue for the updater. dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that handles the updates and dispatches them to the handlers. running (:obj:`bool`): Indicates if the updater is running. persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to store data that should be persistent over restarts. use_context (:obj:`bool`): Optional. :obj:`True` if using context based callbacks. Args: token (:obj:`str`, optional): The bot's token given by the @BotFather. base_url (:obj:`str`, optional): Base_url for the bot. base_file_url (:obj:`str`, optional): Base_file_url for the bot. workers (:obj:`int`, optional): Amount of threads in the thread pool for functions decorated with ``@run_async`` (ignored if `dispatcher` argument is used). bot (:class:`telegram.Bot`, optional): A pre-initialized bot instance (ignored if `dispatcher` argument is used). If a pre-initialized bot is used, it is the user's responsibility to create it using a `Request` instance with a large enough connection pool. dispatcher (:class:`telegram.ext.Dispatcher`, optional): A pre-initialized dispatcher instance. If a pre-initialized dispatcher is used, it is the user's responsibility to create it with proper arguments. private_key (:obj:`bytes`, optional): Private key for decryption of telegram passport data. private_key_password (:obj:`bytes`, optional): Password for above private key. user_sig_handler (:obj:`function`, optional): Takes ``signum, frame`` as positional arguments. This will be called when a signal is received, defaults are (SIGINT, SIGTERM, SIGABRT) settable with :attr:`idle`. request_kwargs (:obj:`dict`, optional): Keyword args to control the creation of a `telegram.utils.request.Request` object (ignored if `bot` or `dispatcher` argument is used). The request_kwargs are very useful for the advanced users who would like to control the default timeouts and/or control the proxy used for http communication. use_context (:obj:`bool`, optional): If set to :obj:`True` uses the context based callback API (ignored if `dispatcher` argument is used). Defaults to :obj:`True`. **New users**: set this to :obj:`True`. persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to store data that should be persistent over restarts (ignored if `dispatcher` argument is used). defaults (:class:`telegram.ext.Defaults`, optional): An object containing default values to be used if not set explicitly in the bot methods. Note: * You must supply either a :attr:`bot` or a :attr:`token` argument. * If you supply a :attr:`bot`, you will need to pass :attr:`defaults` to *both* the bot and the :class:`telegram.ext.Updater`. Raises: ValueError: If both :attr:`token` and :attr:`bot` are passed or none of them. """ _request = None def __init__( self, token: str = None, base_url: str = None, workers: int = 4, bot: Bot = None, private_key: bytes = None, private_key_password: bytes = None, user_sig_handler: Callable = None, request_kwargs: Dict[str, Any] = None, persistence: 'BasePersistence' = None, defaults: 'Defaults' = None, use_context: bool = True, dispatcher: Dispatcher = None, base_file_url: str = None, ): if defaults and bot: warnings.warn( 'Passing defaults to an Updater has no effect when a Bot is passed ' 'as well. Pass them to the Bot instead.', TelegramDeprecationWarning, stacklevel=2, ) if dispatcher is None: if (token is None) and (bot is None): raise ValueError('`token` or `bot` must be passed') if (token is not None) and (bot is not None): raise ValueError('`token` and `bot` are mutually exclusive') if (private_key is not None) and (bot is not None): raise ValueError('`bot` and `private_key` are mutually exclusive') else: if bot is not None: raise ValueError('`dispatcher` and `bot` are mutually exclusive') if persistence is not None: raise ValueError('`dispatcher` and `persistence` are mutually exclusive') if workers is not None: raise ValueError('`dispatcher` and `workers` are mutually exclusive') if use_context != dispatcher.use_context: raise ValueError('`dispatcher` and `use_context` are mutually exclusive') self.logger = logging.getLogger(__name__) if dispatcher is None: con_pool_size = workers + 4 if bot is not None: self.bot = bot if bot.request.con_pool_size < con_pool_size: self.logger.warning( 'Connection pool of Request object is smaller than optimal value (%s)', con_pool_size, ) else: # we need a connection pool the size of: # * for each of the workers # * 1 for Dispatcher # * 1 for polling Updater (even if webhook is used, we can spare a connection) # * 1 for JobQueue # * 1 for main thread if request_kwargs is None: request_kwargs = {} if 'con_pool_size' not in request_kwargs: request_kwargs['con_pool_size'] = con_pool_size self._request = Request(**request_kwargs) self.bot = Bot( token, # type: ignore[arg-type] base_url, base_file_url=base_file_url, request=self._request, private_key=private_key, private_key_password=private_key_password, defaults=defaults, ) self.update_queue: Queue = Queue() self.job_queue = JobQueue() self.__exception_event = Event() self.persistence = persistence self.dispatcher = Dispatcher( self.bot, self.update_queue, job_queue=self.job_queue, workers=workers, exception_event=self.__exception_event, persistence=persistence, use_context=use_context, ) self.job_queue.set_dispatcher(self.dispatcher) else: con_pool_size = dispatcher.workers + 4 self.bot = dispatcher.bot if self.bot.request.con_pool_size < con_pool_size: self.logger.warning( 'Connection pool of Request object is smaller than optimal value (%s)', con_pool_size, ) self.update_queue = dispatcher.update_queue self.__exception_event = dispatcher.exception_event self.persistence = dispatcher.persistence self.job_queue = dispatcher.job_queue self.dispatcher = dispatcher self.user_sig_handler = user_sig_handler self.last_update_id = 0 self.running = False self.is_idle = False self.httpd = None self.__lock = Lock() self.__threads: List[Thread] = [] def _init_thread(self, target: Callable, name: str, *args: Any, **kwargs: Any) -> None: thr = Thread( target=self._thread_wrapper, name="Bot:{}:{}".format(self.bot.id, name), args=(target,) + args, kwargs=kwargs, ) thr.start() self.__threads.append(thr) def _thread_wrapper(self, target: Callable, *args: Any, **kwargs: Any) -> None: thr_name = current_thread().name self.logger.debug('%s - started', thr_name) try: target(*args, **kwargs) except Exception: self.__exception_event.set() self.logger.exception('unhandled exception in %s', thr_name) raise self.logger.debug('%s - ended', thr_name) def start_polling( self, poll_interval: float = 0.0, timeout: float = 10, clean: bool = False, bootstrap_retries: int = -1, read_latency: float = 2.0, allowed_updates: List[str] = None, ) -> Optional[Queue]: """Starts polling updates from Telegram. Args: poll_interval (:obj:`float`, optional): Time to wait between polling updates from Telegram in seconds. Default is 0.0. timeout (:obj:`float`, optional): Passed to :attr:`telegram.Bot.get_updates`. clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is :obj:`False`. bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the `Updater` will retry on failures on the Telegram server. * < 0 - retry indefinitely (default) * 0 - no retries * > 0 - retry up to X times allowed_updates (List[:obj:`str`], optional): Passed to :attr:`telegram.Bot.get_updates`. read_latency (:obj:`float` | :obj:`int`, optional): Grace time in seconds for receiving the reply from server. Will be added to the `timeout` value and used as the read timeout from server (Default: 2). Returns: :obj:`Queue`: The update queue that can be filled from the main thread. """ with self.__lock: if not self.running: self.running = True # Create & start threads self.job_queue.start() dispatcher_ready = Event() polling_ready = Event() self._init_thread(self.dispatcher.start, "dispatcher", ready=dispatcher_ready) self._init_thread( self._start_polling, "updater", poll_interval, timeout, read_latency, bootstrap_retries, clean, allowed_updates, ready=polling_ready, ) self.logger.debug('Waiting for Dispatcher and polling to start') dispatcher_ready.wait() polling_ready.wait() # Return the update queue so the main thread can insert updates return self.update_queue return None def start_webhook( self, listen: str = '127.0.0.1', port: int = 80, url_path: str = '', cert: str = None, key: str = None, clean: bool = False, bootstrap_retries: int = 0, webhook_url: str = None, allowed_updates: List[str] = None, force_event_loop: bool = False, ) -> Optional[Queue]: """ Starts a small http server to listen for updates via webhook. If cert and key are not provided, the webhook will be started directly on http://listen:port/url_path, so SSL can be handled by another application. Else, the webhook will be started on https://listen:port/url_path Note: Due to an incompatibility of the Tornado library PTB uses for the webhook with Python 3.8+ on Windows machines, PTB will attempt to set the event loop to :attr:`asyncio.SelectorEventLoop` and raise an exception, if an incompatible event loop has already been specified. See this `thread`_ for more details. To suppress the exception, set :attr:`force_event_loop` to :obj:`True`. .. _thread: https://github.com/tornadoweb/tornado/issues/2608 Args: listen (:obj:`str`, optional): IP-Address to listen on. Default ``127.0.0.1``. port (:obj:`int`, optional): Port the bot should be listening on. Default ``80``. url_path (:obj:`str`, optional): Path inside url. cert (:obj:`str`, optional): Path to the SSL certificate file. key (:obj:`str`, optional): Path to the SSL key file. clean (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers before actually starting the webhook. Default is :obj:`False`. bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the `Updater` will retry on failures on the Telegram server. * < 0 - retry indefinitely (default) * 0 - no retries * > 0 - retry up to X times webhook_url (:obj:`str`, optional): Explicitly specify the webhook url. Useful behind NAT, reverse proxy, etc. Default is derived from `listen`, `port` & `url_path`. allowed_updates (List[:obj:`str`], optional): Passed to :attr:`telegram.Bot.set_webhook`. force_event_loop (:obj:`bool`, optional): Force using the current event loop. See above note for details. Defaults to :obj:`False` Returns: :obj:`Queue`: The update queue that can be filled from the main thread. """ with self.__lock: if not self.running: self.running = True # Create & start threads webhook_ready = Event() dispatcher_ready = Event() self.job_queue.start() self._init_thread(self.dispatcher.start, "dispatcher", dispatcher_ready) self._init_thread( self._start_webhook, "updater", listen, port, url_path, cert, key, bootstrap_retries, clean, webhook_url, allowed_updates, ready=webhook_ready, force_event_loop=force_event_loop, ) self.logger.debug('Waiting for Dispatcher and Webhook to start') webhook_ready.wait() dispatcher_ready.wait() # Return the update queue so the main thread can insert updates return self.update_queue return None @no_type_check def _start_polling( self, poll_interval, timeout, read_latency, bootstrap_retries, clean, allowed_updates, ready=None, ): # pragma: no cover # Thread target of thread 'updater'. Runs in background, pulls # updates from Telegram and inserts them in the update queue of the # Dispatcher. self.logger.debug('Updater thread started (polling)') self._bootstrap(bootstrap_retries, clean=clean, webhook_url='', allowed_updates=None) self.logger.debug('Bootstrap done') def polling_action_cb(): updates = self.bot.get_updates( self.last_update_id, timeout=timeout, read_latency=read_latency, allowed_updates=allowed_updates, ) if updates: if not self.running: self.logger.debug('Updates ignored and will be pulled again on restart') else: for update in updates: self.update_queue.put(update) self.last_update_id = updates[-1].update_id + 1 return True def polling_onerr_cb(exc): # Put the error into the update queue and let the Dispatcher # broadcast it self.update_queue.put(exc) if ready is not None: ready.set() self._network_loop_retry( polling_action_cb, polling_onerr_cb, 'getting Updates', poll_interval ) @no_type_check def _network_loop_retry(self, action_cb, onerr_cb, description, interval): """Perform a loop calling `action_cb`, retrying after network errors. Stop condition for loop: `self.running` evaluates :obj:`False` or return value of `action_cb` evaluates :obj:`False`. Args: action_cb (:obj:`callable`): Network oriented callback function to call. onerr_cb (:obj:`callable`): Callback to call when TelegramError is caught. Receives the exception object as a parameter. description (:obj:`str`): Description text to use for logs and exception raised. interval (:obj:`float` | :obj:`int`): Interval to sleep between each call to `action_cb`. """ self.logger.debug('Start network loop retry %s', description) cur_interval = interval while self.running: try: if not action_cb(): break except RetryAfter as exc: self.logger.info('%s', exc) cur_interval = 0.5 + exc.retry_after except TimedOut as toe: self.logger.debug('Timed out %s: %s', description, toe) # If failure is due to timeout, we should retry asap. cur_interval = 0 except InvalidToken as pex: self.logger.error('Invalid token; aborting') raise pex except TelegramError as telegram_exc: self.logger.error('Error while %s: %s', description, telegram_exc) onerr_cb(telegram_exc) cur_interval = self._increase_poll_interval(cur_interval) else: cur_interval = interval if cur_interval: sleep(cur_interval) @staticmethod def _increase_poll_interval(current_interval: float) -> float: # increase waiting times on subsequent errors up to 30secs if current_interval == 0: current_interval = 1 elif current_interval < 30: current_interval += current_interval / 2 elif current_interval > 30: current_interval = 30 return current_interval @no_type_check def _start_webhook( self, listen, port, url_path, cert, key, bootstrap_retries, clean, webhook_url, allowed_updates, ready=None, force_event_loop=False, ): self.logger.debug('Updater thread started (webhook)') use_ssl = cert is not None and key is not None if not url_path.startswith('/'): url_path = '/{}'.format(url_path) # Create Tornado app instance app = WebhookAppClass(url_path, self.bot, self.update_queue) # Form SSL Context # An SSLError is raised if the private key does not match with the certificate if use_ssl: try: ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) ssl_ctx.load_cert_chain(cert, key) except ssl.SSLError as exc: raise TelegramError('Invalid SSL Certificate') from exc else: ssl_ctx = None # Create and start server self.httpd = WebhookServer(listen, port, app, ssl_ctx) if use_ssl: # DO NOT CHANGE: Only set webhook if SSL is handled by library if not webhook_url: webhook_url = self._gen_webhook_url(listen, port, url_path) self._bootstrap( max_retries=bootstrap_retries, clean=clean, webhook_url=webhook_url, cert=open(cert, 'rb'), allowed_updates=allowed_updates, ) elif clean: self.logger.warning( "cleaning updates is not supported if " "SSL-termination happens elsewhere; skipping" ) self.httpd.serve_forever(force_event_loop=force_event_loop, ready=ready) @staticmethod def _gen_webhook_url(listen: str, port: int, url_path: str) -> str: return 'https://{listen}:{port}{path}'.format(listen=listen, port=port, path=url_path) @no_type_check def _bootstrap( self, max_retries, clean, webhook_url, allowed_updates, cert=None, bootstrap_interval=5 ): retries = [0] def bootstrap_del_webhook(): self.bot.delete_webhook() return False def bootstrap_clean_updates(): self.logger.debug('Cleaning updates from Telegram server') updates = self.bot.get_updates() while updates: updates = self.bot.get_updates(updates[-1].update_id + 1) return False def bootstrap_set_webhook(): self.bot.set_webhook( url=webhook_url, certificate=cert, allowed_updates=allowed_updates ) return False def bootstrap_onerr_cb(exc): if not isinstance(exc, Unauthorized) and (max_retries < 0 or retries[0] < max_retries): retries[0] += 1 self.logger.warning( 'Failed bootstrap phase; try=%s max_retries=%s', retries[0], max_retries ) else: self.logger.error('Failed bootstrap phase after %s retries (%s)', retries[0], exc) raise exc # Cleaning pending messages is done by polling for them - so we need to delete webhook if # one is configured. # We also take this chance to delete pre-configured webhook if this is a polling Updater. # NOTE: We don't know ahead if a webhook is configured, so we just delete. if clean or not webhook_url: self._network_loop_retry( bootstrap_del_webhook, bootstrap_onerr_cb, 'bootstrap del webhook', bootstrap_interval, ) retries[0] = 0 # Clean pending messages, if requested. if clean: self._network_loop_retry( bootstrap_clean_updates, bootstrap_onerr_cb, 'bootstrap clean updates', bootstrap_interval, ) retries[0] = 0 sleep(1) # Restore/set webhook settings, if needed. Again, we don't know ahead if a webhook is set, # so we set it anyhow. if webhook_url: self._network_loop_retry( bootstrap_set_webhook, bootstrap_onerr_cb, 'bootstrap set webhook', bootstrap_interval, ) def stop(self) -> None: """Stops the polling/webhook thread, the dispatcher and the job queue.""" self.job_queue.stop() with self.__lock: if self.running or self.dispatcher.has_running_threads: self.logger.debug('Stopping Updater and Dispatcher...') self.running = False self._stop_httpd() self._stop_dispatcher() self._join_threads() # Stop the Request instance only if it was created by the Updater if self._request: self._request.stop() @no_type_check def _stop_httpd(self) -> None: if self.httpd: self.logger.debug( 'Waiting for current webhook connection to be ' 'closed... Send a Telegram message to the bot to exit ' 'immediately.' ) self.httpd.shutdown() self.httpd = None @no_type_check def _stop_dispatcher(self) -> None: self.logger.debug('Requesting Dispatcher to stop...') self.dispatcher.stop() @no_type_check def _join_threads(self) -> None: for thr in self.__threads: self.logger.debug('Waiting for %s thread to end', thr.name) thr.join() self.logger.debug('%s thread has ended', thr.name) self.__threads = [] @no_type_check def signal_handler(self, signum, frame) -> None: self.is_idle = False if self.running: self.logger.info( 'Received signal %s (%s), stopping...', signum, get_signal_name(signum) ) if self.persistence: # Update user_data, chat_data and bot_data before flushing self.dispatcher.update_persistence() self.persistence.flush() self.stop() if self.user_sig_handler: self.user_sig_handler(signum, frame) else: self.logger.warning('Exiting immediately!') # pylint: disable=C0415,W0212 import os os._exit(1) def idle(self, stop_signals: Union[List, Tuple] = (SIGINT, SIGTERM, SIGABRT)) -> None: """Blocks until one of the signals are received and stops the updater. Args: stop_signals (:obj:`list` | :obj:`tuple`): List containing signals from the signal module that should be subscribed to. Updater.stop() will be called on receiving one of those signals. Defaults to (``SIGINT``, ``SIGTERM``, ``SIGABRT``). """ for sig in stop_signals: signal(sig, self.signal_handler) self.is_idle = True while self.is_idle: sleep(1)
class Updater(Generic[CCT, UD, CD, BD]): """ This class, which employs the :class:`telegram.ext.Dispatcher`, provides a frontend to :class:`telegram.Bot` to the programmer, so they can focus on coding the bot. Its purpose is to receive the updates from Telegram and to deliver them to said dispatcher. It also runs in a separate thread, so the user can interact with the bot, for example on the command line. The dispatcher supports handlers for different kinds of data: Updates from Telegram, basic text commands and even arbitrary types. The updater can be started as a polling service or, for production, use a webhook to receive updates. This is achieved using the WebhookServer and WebhookHandler classes. Note: * You must supply either a :attr:`bot` or a :attr:`token` argument. * If you supply a :attr:`bot`, you will need to pass :attr:`arbitrary_callback_data`, and :attr:`defaults` to the bot instead of the :class:`telegram.ext.Updater`. In this case, you'll have to use the class :class:`telegram.ext.ExtBot`. .. versionchanged:: 13.6 Args: token (:obj:`str`, optional): The bot's token given by the @BotFather. base_url (:obj:`str`, optional): Base_url for the bot. base_file_url (:obj:`str`, optional): Base_file_url for the bot. workers (:obj:`int`, optional): Amount of threads in the thread pool for functions decorated with ``@run_async`` (ignored if `dispatcher` argument is used). bot (:class:`telegram.Bot`, optional): A pre-initialized bot instance (ignored if `dispatcher` argument is used). If a pre-initialized bot is used, it is the user's responsibility to create it using a `Request` instance with a large enough connection pool. dispatcher (:class:`telegram.ext.Dispatcher`, optional): A pre-initialized dispatcher instance. If a pre-initialized dispatcher is used, it is the user's responsibility to create it with proper arguments. private_key (:obj:`bytes`, optional): Private key for decryption of telegram passport data. private_key_password (:obj:`bytes`, optional): Password for above private key. user_sig_handler (:obj:`function`, optional): Takes ``signum, frame`` as positional arguments. This will be called when a signal is received, defaults are (SIGINT, SIGTERM, SIGABRT) settable with :attr:`idle`. request_kwargs (:obj:`dict`, optional): Keyword args to control the creation of a `telegram.utils.request.Request` object (ignored if `bot` or `dispatcher` argument is used). The request_kwargs are very useful for the advanced users who would like to control the default timeouts and/or control the proxy used for http communication. use_context (:obj:`bool`, optional): If set to :obj:`True` uses the context based callback API (ignored if `dispatcher` argument is used). Defaults to :obj:`True`. **New users**: set this to :obj:`True`. persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to store data that should be persistent over restarts (ignored if `dispatcher` argument is used). defaults (:class:`telegram.ext.Defaults`, optional): An object containing default values to be used if not set explicitly in the bot methods. arbitrary_callback_data (:obj:`bool` | :obj:`int` | :obj:`None`, optional): Whether to allow arbitrary objects as callback data for :class:`telegram.InlineKeyboardButton`. Pass an integer to specify the maximum number of cached objects. For more details, please see our wiki. Defaults to :obj:`False`. .. versionadded:: 13.6 context_types (:class:`telegram.ext.ContextTypes`, optional): Pass an instance of :class:`telegram.ext.ContextTypes` to customize the types used in the ``context`` interface. If not passed, the defaults documented in :class:`telegram.ext.ContextTypes` will be used. .. versionadded:: 13.6 Raises: ValueError: If both :attr:`token` and :attr:`bot` are passed or none of them. Attributes: bot (:class:`telegram.Bot`): The bot used with this Updater. user_sig_handler (:obj:`function`): Optional. Function to be called when a signal is received. update_queue (:obj:`Queue`): Queue for the updates. job_queue (:class:`telegram.ext.JobQueue`): Jobqueue for the updater. dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that handles the updates and dispatches them to the handlers. running (:obj:`bool`): Indicates if the updater is running. persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to store data that should be persistent over restarts. use_context (:obj:`bool`): Optional. :obj:`True` if using context based callbacks. """ __slots__ = ( 'persistence', 'dispatcher', 'user_sig_handler', 'bot', 'logger', 'update_queue', 'job_queue', '__exception_event', 'last_update_id', 'running', '_request', 'is_idle', 'httpd', '__lock', '__threads', '__dict__', ) @overload def __init__( self: 'Updater[CallbackContext, dict, dict, dict]', token: str = None, base_url: str = None, workers: int = 4, bot: Bot = None, private_key: bytes = None, private_key_password: bytes = None, user_sig_handler: Callable = None, request_kwargs: Dict[str, Any] = None, persistence: 'BasePersistence' = None, # pylint: disable=E0601 defaults: 'Defaults' = None, use_context: bool = True, base_file_url: str = None, arbitrary_callback_data: Union[DefaultValue, bool, int, None] = DEFAULT_FALSE, ): ... @overload def __init__( self: 'Updater[CCT, UD, CD, BD]', token: str = None, base_url: str = None, workers: int = 4, bot: Bot = None, private_key: bytes = None, private_key_password: bytes = None, user_sig_handler: Callable = None, request_kwargs: Dict[str, Any] = None, persistence: 'BasePersistence' = None, defaults: 'Defaults' = None, use_context: bool = True, base_file_url: str = None, arbitrary_callback_data: Union[DefaultValue, bool, int, None] = DEFAULT_FALSE, context_types: ContextTypes[CCT, UD, CD, BD] = None, ): ... @overload def __init__( self: 'Updater[CCT, UD, CD, BD]', user_sig_handler: Callable = None, dispatcher: Dispatcher[CCT, UD, CD, BD] = None, ): ... def __init__( # type: ignore[no-untyped-def,misc] self, token: str = None, base_url: str = None, workers: int = 4, bot: Bot = None, private_key: bytes = None, private_key_password: bytes = None, user_sig_handler: Callable = None, request_kwargs: Dict[str, Any] = None, persistence: 'BasePersistence' = None, defaults: 'Defaults' = None, use_context: bool = True, dispatcher=None, base_file_url: str = None, arbitrary_callback_data: Union[DefaultValue, bool, int, None] = DEFAULT_FALSE, context_types: ContextTypes[CCT, UD, CD, BD] = None, ): if defaults and bot: warnings.warn( 'Passing defaults to an Updater has no effect when a Bot is passed ' 'as well. Pass them to the Bot instead.', TelegramDeprecationWarning, stacklevel=2, ) if arbitrary_callback_data is not DEFAULT_FALSE and bot: warnings.warn( 'Passing arbitrary_callback_data to an Updater has no ' 'effect when a Bot is passed as well. Pass them to the Bot instead.', stacklevel=2, ) if dispatcher is None: if (token is None) and (bot is None): raise ValueError('`token` or `bot` must be passed') if (token is not None) and (bot is not None): raise ValueError('`token` and `bot` are mutually exclusive') if (private_key is not None) and (bot is not None): raise ValueError( '`bot` and `private_key` are mutually exclusive') else: if bot is not None: raise ValueError( '`dispatcher` and `bot` are mutually exclusive') if persistence is not None: raise ValueError( '`dispatcher` and `persistence` are mutually exclusive') if use_context != dispatcher.use_context: raise ValueError( '`dispatcher` and `use_context` are mutually exclusive') if context_types is not None: raise ValueError( '`dispatcher` and `context_types` are mutually exclusive') if workers is not None: raise ValueError( '`dispatcher` and `workers` are mutually exclusive') self.logger = logging.getLogger(__name__) self._request = None if dispatcher is None: con_pool_size = workers + 4 if bot is not None: self.bot = bot if bot.request.con_pool_size < con_pool_size: self.logger.warning( 'Connection pool of Request object is smaller than optimal value (%s)', con_pool_size, ) else: # we need a connection pool the size of: # * for each of the workers # * 1 for Dispatcher # * 1 for polling Updater (even if webhook is used, we can spare a connection) # * 1 for JobQueue # * 1 for main thread if request_kwargs is None: request_kwargs = {} if 'con_pool_size' not in request_kwargs: request_kwargs['con_pool_size'] = con_pool_size self._request = Request(**request_kwargs) self.bot = ExtBot( token, # type: ignore[arg-type] base_url, base_file_url=base_file_url, request=self._request, private_key=private_key, private_key_password=private_key_password, defaults=defaults, arbitrary_callback_data=( False # type: ignore[arg-type] if arbitrary_callback_data is DEFAULT_FALSE else arbitrary_callback_data), ) self.update_queue: Queue = Queue() self.job_queue = JobQueue() self.__exception_event = Event() self.persistence = persistence self.dispatcher = Dispatcher( self.bot, self.update_queue, job_queue=self.job_queue, workers=workers, exception_event=self.__exception_event, persistence=persistence, use_context=use_context, context_types=context_types, ) self.job_queue.set_dispatcher(self.dispatcher) else: con_pool_size = dispatcher.workers + 4 self.bot = dispatcher.bot if self.bot.request.con_pool_size < con_pool_size: self.logger.warning( 'Connection pool of Request object is smaller than optimal value (%s)', con_pool_size, ) self.update_queue = dispatcher.update_queue self.__exception_event = dispatcher.exception_event self.persistence = dispatcher.persistence self.job_queue = dispatcher.job_queue self.dispatcher = dispatcher self.user_sig_handler = user_sig_handler self.last_update_id = 0 self.running = False self.is_idle = False self.httpd = None self.__lock = Lock() self.__threads: List[Thread] = [] def __setattr__(self, key: str, value: object) -> None: if key.startswith('__'): key = f"_{self.__class__.__name__}{key}" if issubclass(self.__class__, Updater) and self.__class__ is not Updater: object.__setattr__(self, key, value) return set_new_attribute_deprecated(self, key, value) def _init_thread(self, target: Callable, name: str, *args: object, **kwargs: object) -> None: thr = Thread( target=self._thread_wrapper, name=f"Bot:{self.bot.id}:{name}", args=(target, ) + args, kwargs=kwargs, ) thr.start() self.__threads.append(thr) def _thread_wrapper(self, target: Callable, *args: object, **kwargs: object) -> None: thr_name = current_thread().name self.logger.debug('%s - started', thr_name) try: target(*args, **kwargs) except Exception: self.__exception_event.set() self.logger.exception('unhandled exception in %s', thr_name) raise self.logger.debug('%s - ended', thr_name) def start_polling( self, poll_interval: float = 0.0, timeout: float = 10, clean: bool = None, bootstrap_retries: int = -1, read_latency: float = 2.0, allowed_updates: List[str] = None, drop_pending_updates: bool = None, ) -> Optional[Queue]: """Starts polling updates from Telegram. Args: poll_interval (:obj:`float`, optional): Time to wait between polling updates from Telegram in seconds. Default is ``0.0``. timeout (:obj:`float`, optional): Passed to :meth:`telegram.Bot.get_updates`. drop_pending_updates (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is :obj:`False`. .. versionadded :: 13.4 clean (:obj:`bool`, optional): Alias for ``drop_pending_updates``. .. deprecated:: 13.4 Use ``drop_pending_updates`` instead. bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the :class:`telegram.ext.Updater` will retry on failures on the Telegram server. * < 0 - retry indefinitely (default) * 0 - no retries * > 0 - retry up to X times allowed_updates (List[:obj:`str`], optional): Passed to :meth:`telegram.Bot.get_updates`. read_latency (:obj:`float` | :obj:`int`, optional): Grace time in seconds for receiving the reply from server. Will be added to the ``timeout`` value and used as the read timeout from server (Default: ``2``). Returns: :obj:`Queue`: The update queue that can be filled from the main thread. """ if (clean is not None) and (drop_pending_updates is not None): raise TypeError( '`clean` and `drop_pending_updates` are mutually exclusive.') if clean is not None: warnings.warn( 'The argument `clean` of `start_polling` is deprecated. Please use ' '`drop_pending_updates` instead.', category=TelegramDeprecationWarning, stacklevel=2, ) drop_pending_updates = drop_pending_updates if drop_pending_updates is not None else clean with self.__lock: if not self.running: self.running = True # Create & start threads self.job_queue.start() dispatcher_ready = Event() polling_ready = Event() self._init_thread(self.dispatcher.start, "dispatcher", ready=dispatcher_ready) self._init_thread( self._start_polling, "updater", poll_interval, timeout, read_latency, bootstrap_retries, drop_pending_updates, allowed_updates, ready=polling_ready, ) self.logger.debug( 'Waiting for Dispatcher and polling to start') dispatcher_ready.wait() polling_ready.wait() # Return the update queue so the main thread can insert updates return self.update_queue return None def start_webhook( self, listen: str = '127.0.0.1', port: int = 80, url_path: str = '', cert: str = None, key: str = None, clean: bool = None, bootstrap_retries: int = 0, webhook_url: str = None, allowed_updates: List[str] = None, force_event_loop: bool = None, drop_pending_updates: bool = None, ip_address: str = None, max_connections: int = 40, ) -> Optional[Queue]: """ Starts a small http server to listen for updates via webhook. If :attr:`cert` and :attr:`key` are not provided, the webhook will be started directly on http://listen:port/url_path, so SSL can be handled by another application. Else, the webhook will be started on https://listen:port/url_path. Also calls :meth:`telegram.Bot.set_webhook` as required. .. versionchanged:: 13.4 :meth:`start_webhook` now *always* calls :meth:`telegram.Bot.set_webhook`, so pass ``webhook_url`` instead of calling ``updater.bot.set_webhook(webhook_url)`` manually. Args: listen (:obj:`str`, optional): IP-Address to listen on. Default ``127.0.0.1``. port (:obj:`int`, optional): Port the bot should be listening on. Default ``80``. url_path (:obj:`str`, optional): Path inside url. cert (:obj:`str`, optional): Path to the SSL certificate file. key (:obj:`str`, optional): Path to the SSL key file. drop_pending_updates (:obj:`bool`, optional): Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is :obj:`False`. .. versionadded :: 13.4 clean (:obj:`bool`, optional): Alias for ``drop_pending_updates``. .. deprecated:: 13.4 Use ``drop_pending_updates`` instead. bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the :class:`telegram.ext.Updater` will retry on failures on the Telegram server. * < 0 - retry indefinitely (default) * 0 - no retries * > 0 - retry up to X times webhook_url (:obj:`str`, optional): Explicitly specify the webhook url. Useful behind NAT, reverse proxy, etc. Default is derived from ``listen``, ``port`` & ``url_path``. ip_address (:obj:`str`, optional): Passed to :meth:`telegram.Bot.set_webhook`. .. versionadded :: 13.4 allowed_updates (List[:obj:`str`], optional): Passed to :meth:`telegram.Bot.set_webhook`. force_event_loop (:obj:`bool`, optional): Legacy parameter formerly used for a workaround on Windows + Python 3.8+. No longer has any effect. .. deprecated:: 13.6 Since version 13.6, ``tornade>=6.1`` is required, which resolves the former issue. max_connections (:obj:`int`, optional): Passed to :meth:`telegram.Bot.set_webhook`. .. versionadded:: 13.6 Returns: :obj:`Queue`: The update queue that can be filled from the main thread. """ if (clean is not None) and (drop_pending_updates is not None): raise TypeError( '`clean` and `drop_pending_updates` are mutually exclusive.') if clean is not None: warnings.warn( 'The argument `clean` of `start_webhook` is deprecated. Please use ' '`drop_pending_updates` instead.', category=TelegramDeprecationWarning, stacklevel=2, ) if force_event_loop is not None: warnings.warn( 'The argument `force_event_loop` of `start_webhook` is deprecated and no longer ' 'has any effect.', category=TelegramDeprecationWarning, stacklevel=2, ) drop_pending_updates = drop_pending_updates if drop_pending_updates is not None else clean with self.__lock: if not self.running: self.running = True # Create & start threads webhook_ready = Event() dispatcher_ready = Event() self.job_queue.start() self._init_thread(self.dispatcher.start, "dispatcher", dispatcher_ready) self._init_thread( self._start_webhook, "updater", listen, port, url_path, cert, key, bootstrap_retries, drop_pending_updates, webhook_url, allowed_updates, ready=webhook_ready, ip_address=ip_address, max_connections=max_connections, ) self.logger.debug( 'Waiting for Dispatcher and Webhook to start') webhook_ready.wait() dispatcher_ready.wait() # Return the update queue so the main thread can insert updates return self.update_queue return None @no_type_check def _start_polling( self, poll_interval, timeout, read_latency, bootstrap_retries, drop_pending_updates, allowed_updates, ready=None, ): # pragma: no cover # Thread target of thread 'updater'. Runs in background, pulls # updates from Telegram and inserts them in the update queue of the # Dispatcher. self.logger.debug('Updater thread started (polling)') self._bootstrap( bootstrap_retries, drop_pending_updates=drop_pending_updates, webhook_url='', allowed_updates=None, ) self.logger.debug('Bootstrap done') def polling_action_cb(): updates = self.bot.get_updates( self.last_update_id, timeout=timeout, read_latency=read_latency, allowed_updates=allowed_updates, ) if updates: if not self.running: self.logger.debug( 'Updates ignored and will be pulled again on restart') else: for update in updates: self.update_queue.put(update) self.last_update_id = updates[-1].update_id + 1 return True def polling_onerr_cb(exc): # Put the error into the update queue and let the Dispatcher # broadcast it self.update_queue.put(exc) if ready is not None: ready.set() self._network_loop_retry(polling_action_cb, polling_onerr_cb, 'getting Updates', poll_interval) @no_type_check def _network_loop_retry(self, action_cb, onerr_cb, description, interval): """Perform a loop calling `action_cb`, retrying after network errors. Stop condition for loop: `self.running` evaluates :obj:`False` or return value of `action_cb` evaluates :obj:`False`. Args: action_cb (:obj:`callable`): Network oriented callback function to call. onerr_cb (:obj:`callable`): Callback to call when TelegramError is caught. Receives the exception object as a parameter. description (:obj:`str`): Description text to use for logs and exception raised. interval (:obj:`float` | :obj:`int`): Interval to sleep between each call to `action_cb`. """ self.logger.debug('Start network loop retry %s', description) cur_interval = interval while self.running: try: if not action_cb(): break except RetryAfter as exc: self.logger.info('%s', exc) cur_interval = 0.5 + exc.retry_after except TimedOut as toe: self.logger.debug('Timed out %s: %s', description, toe) # If failure is due to timeout, we should retry asap. cur_interval = 0 except InvalidToken as pex: self.logger.error('Invalid token; aborting') raise pex except TelegramError as telegram_exc: self.logger.error('Error while %s: %s', description, telegram_exc) onerr_cb(telegram_exc) cur_interval = self._increase_poll_interval(cur_interval) else: cur_interval = interval if cur_interval: sleep(cur_interval) @staticmethod def _increase_poll_interval(current_interval: float) -> float: # increase waiting times on subsequent errors up to 30secs if current_interval == 0: current_interval = 1 elif current_interval < 30: current_interval *= 1.5 else: current_interval = min(30.0, current_interval) return current_interval @no_type_check def _start_webhook( self, listen, port, url_path, cert, key, bootstrap_retries, drop_pending_updates, webhook_url, allowed_updates, ready=None, ip_address=None, max_connections: int = 40, ): self.logger.debug('Updater thread started (webhook)') # Note that we only use the SSL certificate for the WebhookServer, if the key is also # present. This is because the WebhookServer may not actually be in charge of performing # the SSL handshake, e.g. in case a reverse proxy is used use_ssl = cert is not None and key is not None if not url_path.startswith('/'): url_path = f'/{url_path}' # Create Tornado app instance app = WebhookAppClass(url_path, self.bot, self.update_queue) # Form SSL Context # An SSLError is raised if the private key does not match with the certificate if use_ssl: try: ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) ssl_ctx.load_cert_chain(cert, key) except ssl.SSLError as exc: raise TelegramError('Invalid SSL Certificate') from exc else: ssl_ctx = None # Create and start server self.httpd = WebhookServer(listen, port, app, ssl_ctx) if not webhook_url: webhook_url = self._gen_webhook_url(listen, port, url_path) # We pass along the cert to the webhook if present. cert_file = open(cert, 'rb') if cert is not None else None self._bootstrap( max_retries=bootstrap_retries, drop_pending_updates=drop_pending_updates, webhook_url=webhook_url, allowed_updates=allowed_updates, cert=cert_file, ip_address=ip_address, max_connections=max_connections, ) if cert_file is not None: cert_file.close() self.httpd.serve_forever(ready=ready) @staticmethod def _gen_webhook_url(listen: str, port: int, url_path: str) -> str: return f'https://{listen}:{port}{url_path}' @no_type_check def _bootstrap( self, max_retries, drop_pending_updates, webhook_url, allowed_updates, cert=None, bootstrap_interval=5, ip_address=None, max_connections: int = 40, ): retries = [0] def bootstrap_del_webhook(): self.logger.debug('Deleting webhook') if drop_pending_updates: self.logger.debug( 'Dropping pending updates from Telegram server') self.bot.delete_webhook(drop_pending_updates=drop_pending_updates) return False def bootstrap_set_webhook(): self.logger.debug('Setting webhook') if drop_pending_updates: self.logger.debug( 'Dropping pending updates from Telegram server') self.bot.set_webhook( url=webhook_url, certificate=cert, allowed_updates=allowed_updates, ip_address=ip_address, drop_pending_updates=drop_pending_updates, max_connections=max_connections, ) return False def bootstrap_onerr_cb(exc): if not isinstance(exc, Unauthorized) and ( max_retries < 0 or retries[0] < max_retries): retries[0] += 1 self.logger.warning( 'Failed bootstrap phase; try=%s max_retries=%s', retries[0], max_retries) else: self.logger.error( 'Failed bootstrap phase after %s retries (%s)', retries[0], exc) raise exc # Dropping pending updates from TG can be efficiently done with the drop_pending_updates # parameter of delete/start_webhook, even in the case of polling. Also we want to make # sure that no webhook is configured in case of polling, so we just always call # delete_webhook for polling if drop_pending_updates or not webhook_url: self._network_loop_retry( bootstrap_del_webhook, bootstrap_onerr_cb, 'bootstrap del webhook', bootstrap_interval, ) retries[0] = 0 # Restore/set webhook settings, if needed. Again, we don't know ahead if a webhook is set, # so we set it anyhow. if webhook_url: self._network_loop_retry( bootstrap_set_webhook, bootstrap_onerr_cb, 'bootstrap set webhook', bootstrap_interval, ) def stop(self) -> None: """Stops the polling/webhook thread, the dispatcher and the job queue.""" self.job_queue.stop() with self.__lock: if self.running or self.dispatcher.has_running_threads: self.logger.debug('Stopping Updater and Dispatcher...') self.running = False self._stop_httpd() self._stop_dispatcher() self._join_threads() # Stop the Request instance only if it was created by the Updater if self._request: self._request.stop() @no_type_check def _stop_httpd(self) -> None: if self.httpd: self.logger.debug( 'Waiting for current webhook connection to be ' 'closed... Send a Telegram message to the bot to exit ' 'immediately.') self.httpd.shutdown() self.httpd = None @no_type_check def _stop_dispatcher(self) -> None: self.logger.debug('Requesting Dispatcher to stop...') self.dispatcher.stop() @no_type_check def _join_threads(self) -> None: for thr in self.__threads: self.logger.debug('Waiting for %s thread to end', thr.name) thr.join() self.logger.debug('%s thread has ended', thr.name) self.__threads = [] @no_type_check def _signal_handler(self, signum, frame) -> None: self.is_idle = False if self.running: self.logger.info('Received signal %s (%s), stopping...', signum, get_signal_name(signum)) if self.persistence: # Update user_data, chat_data and bot_data before flushing self.dispatcher.update_persistence() self.persistence.flush() self.stop() if self.user_sig_handler: self.user_sig_handler(signum, frame) else: self.logger.warning('Exiting immediately!') # pylint: disable=C0415,W0212 import os os._exit(1) def idle( self, stop_signals: Union[List, Tuple] = (SIGINT, SIGTERM, SIGABRT) ) -> None: """Blocks until one of the signals are received and stops the updater. Args: stop_signals (:obj:`list` | :obj:`tuple`): List containing signals from the signal module that should be subscribed to. :meth:`Updater.stop()` will be called on receiving one of those signals. Defaults to (``SIGINT``, ``SIGTERM``, ``SIGABRT``). """ for sig in stop_signals: signal(sig, self._signal_handler) self.is_idle = True while self.is_idle: sleep(1)