Updater¶
- class telegram.ext.Updater(bot, update_queue)[source]¶
Bases:
typing.AsyncContextManager
This class fetches updates for the bot either via long polling or by starting a webhook server. Received updates are enqueued into the
update_queue
and may be fetched from there to handle them appropriately.Instances of this class can be used as asyncio context managers, where
async with updater: # code
is roughly equivalent to
try: await updater.initialize() # code finally: await updater.shutdown()
Available In
See also
Changed in version 20.0:
Removed argument and attribute
user_sig_handler
The only arguments and attributes are now
bot
andupdate_queue
as now the sole purpose of this class is to fetch updates. The entry point to a PTB application is nowtelegram.ext.Application
.
- Parameters:
bot (
telegram.Bot
) – The bot used with this Updater.update_queue (
asyncio.Queue
) – Queue for the updates.
- async initialize()[source]¶
Initializes the Updater & the associated
bot
by callingtelegram.Bot.initialize()
.See also
- async shutdown()[source]¶
Shutdown the Updater & the associated
bot
by callingtelegram.Bot.shutdown()
.See also
- Raises:
RuntimeError – If the updater is still running.
- async start_polling(poll_interval=0.0, timeout=10, bootstrap_retries=-1, read_timeout=2, write_timeout=None, connect_timeout=None, pool_timeout=None, allowed_updates=None, drop_pending_updates=None, error_callback=None)[source]¶
Starts polling updates from Telegram.
Changed in version 20.0: Removed the
clean
argument in favor ofdrop_pending_updates
.- Parameters:
poll_interval (
float
, optional) – Time to wait between polling updates from Telegram in seconds. Default is0.0
.timeout (
int
, optional) – Passed totelegram.Bot.get_updates.timeout
. Defaults to10
seconds.bootstrap_retries (
int
, optional) –Whether the bootstrapping phase of the
telegram.ext.Updater
will retry on failures on the Telegram server.< 0 - retry indefinitely (default)
0 - no retries
> 0 - retry up to X times
read_timeout (
float
, optional) – Value to pass totelegram.Bot.get_updates.read_timeout
. Defaults to2
.write_timeout (
float
|None
, optional) – Value to pass totelegram.Bot.get_updates.write_timeout
. Defaults toDEFAULT_NONE
.connect_timeout (
float
|None
, optional) – Value to pass totelegram.Bot.get_updates.connect_timeout
. Defaults toDEFAULT_NONE
.pool_timeout (
float
|None
, optional) – Value to pass totelegram.Bot.get_updates.pool_timeout
. Defaults toDEFAULT_NONE
.allowed_updates (List[
str
], optional) – Passed totelegram.Bot.get_updates()
.drop_pending_updates (
bool
, optional) –Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is
False
.New in version 13.4.
error_callback (Callable[[
telegram.error.TelegramError
],None
], optional) –Callback to handle
telegram.error.TelegramError
s that occur while callingtelegram.Bot.get_updates()
during polling. Defaults toNone
, in which case errors will be logged. Callback signature:def callback(error: telegram.error.TelegramError)
Note
The
error_callback
must not be a coroutine function! If asynchronous behavior of the callback is wanted, please schedule a task from within the callback.
- Returns:
The update queue that can be filled from the main thread.
- Return type:
- Raises:
RuntimeError – If the updater is already running or was not initialized.
- async start_webhook(listen='127.0.0.1', port=80, url_path='', cert=None, key=None, bootstrap_retries=0, webhook_url=None, allowed_updates=None, drop_pending_updates=None, ip_address=None, max_connections=40, secret_token=None)[source]¶
Starts a small http server to listen for updates via webhook. If
cert
andkey
are not provided, the webhook will be started directly onhttp://listen:port/url_path
, so SSL can be handled by another application. Else, the webhook will be started onhttps://listen:port/url_path
. Also callstelegram.Bot.set_webhook()
as required.Important
If you want to use this method, you must install PTB with the optional requirement
webhooks
, i.e.pip install python-telegram-bot[webhooks]
See also
Changed in version 13.4:
start_webhook()
now always callstelegram.Bot.set_webhook()
, so passwebhook_url
instead of callingupdater.bot.set_webhook(webhook_url)
manually.Changed in version 20.0:
Removed the
clean
argument in favor ofdrop_pending_updates
and removed the deprecated argumentforce_event_loop
.
- Parameters:
listen (
str
, optional) – IP-Address to listen on. Defaults to 127.0.0.1.port (
int
, optional) – Port the bot should be listening on. Must be one oftelegram.constants.SUPPORTED_WEBHOOK_PORTS
unless the bot is running behind a proxy. Defaults to80
.url_path (
str
, optional) – Path inside url (http(s)://listen:port/<url_path>). Defaults to''
.cert (
pathlib.Path
|str
, optional) – Path to the SSL certificate file.key (
pathlib.Path
|str
, optional) – Path to the SSL key file.drop_pending_updates (
bool
, optional) –Whether to clean any pending updates on Telegram servers before actually starting to poll. Default is
False
.New in version 13.4.
bootstrap_retries (
int
, optional) –Whether the bootstrapping phase of the
telegram.ext.Updater
will retry on failures on the Telegram server.< 0 - retry indefinitely
0 - no retries (default)
> 0 - retry up to X times
webhook_url (
str
, optional) – Explicitly specify the webhook url. Useful behind NAT, reverse proxy, etc. Default is derived fromlisten
,port
,url_path
,cert
, andkey
.ip_address (
str
, optional) –Passed to
telegram.Bot.set_webhook()
. Defaults toNone
.New in version 13.4.
allowed_updates (List[
str
], optional) – Passed totelegram.Bot.set_webhook()
. Defaults toNone
.max_connections (
int
, optional) –Passed to
telegram.Bot.set_webhook()
. Defaults to40
.New in version 13.6.
secret_token (
str
, optional) –Passed to
telegram.Bot.set_webhook()
. Defaults toNone
.When added, the web server started by this call will expect the token to be set in the
X-Telegram-Bot-Api-Secret-Token
header of an incoming request and will raise ahttp.HTTPStatus.FORBIDDEN
error if either the header isn’t set or it is set to a wrong token.New in version 20.0.
- Returns:
The update queue that can be filled from the main thread.
- Return type:
- Raises:
RuntimeError – If the updater is already running or was not initialized.
- async stop()[source]¶
Stops the polling/webhook.
See also
- Raises:
RuntimeError – If the updater is not running.