Updater¶
- class telegram.ext.Updater(bot, update_queue)[source]¶
Bases:
contextlib.AbstractAsyncContextManager
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
__aenter__()
and__aexit__()
.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 __aenter__()[source]¶
Asynchronous context manager which
initializes
the Updater.- Returns:
The initialized Updater instance.
- Raises:
Exception – If an exception is raised during initialization,
shutdown()
is called in this case.
- async __aexit__(exc_type, exc_val, exc_tb)[source]¶
Asynchronous context manager which
shuts down
the Updater.
- __repr__()[source]¶
Give a string representation of the updater in the form
Updater[bot=...]
.As this class doesn’t implement
object.__str__()
, the default implementation will be used, which is equivalent to__repr__()
.- Returns:
- 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=None, 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 to
telegram.Bot.get_updates.read_timeout
. Defaults toDEFAULT_NONE
.Changed in version 20.7: Defaults to
DEFAULT_NONE
instead of2
.Deprecated since version 20.7: Deprecated in favor of setting the timeout via
telegram.ext.ApplicationBuilder.get_updates_read_timeout()
ortelegram.Bot.get_updates_request
.write_timeout (
float
|None
, optional) –Value to pass to
telegram.Bot.get_updates.write_timeout
. Defaults toDEFAULT_NONE
.Deprecated since version 20.7: Deprecated in favor of setting the timeout via
telegram.ext.ApplicationBuilder.get_updates_write_timeout()
ortelegram.Bot.get_updates_request
.connect_timeout (
float
|None
, optional) –Value to pass to
telegram.Bot.get_updates.connect_timeout
. Defaults toDEFAULT_NONE
.Deprecated since version 20.7: Deprecated in favor of setting the timeout via
telegram.ext.ApplicationBuilder.get_updates_connect_timeout()
ortelegram.Bot.get_updates_request
.pool_timeout (
float
|None
, optional) –Value to pass to
telegram.Bot.get_updates.pool_timeout
. Defaults toDEFAULT_NONE
.Deprecated since version 20.7: Deprecated in favor of setting the timeout via
telegram.ext.ApplicationBuilder.get_updates_pool_timeout()
ortelegram.Bot.get_updates_request
.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
.Added 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, unix=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
.Added 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
.Added 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
.Added 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.Added in version 20.0.
unix (
pathlib.Path
|str
|socket.socket
, optional) –Can be either:
the path to the unix socket file as
pathlib.Path
orstr
. This will be passed to tornado.netutil.bind_unix_socket to create the socket. If the Path does not exist, the file will be created.or the socket itself. This option allows you to e.g. restrict the permissions of the socket for improved security. Note that you need to pass the correct family, type and socket options yourself.
Caution
This parameter is a replacement for the default TCP bind. Therefore, it is mutually exclusive with
listen
andport
. When using this param, you must also run a reverse proxy to the unix socket and set the appropriatewebhook_url
.Added in version 20.8.
Changed in version 21.1: Added support to pass a socket instance itself.
- 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.