Toggle table of contents sidebar
ApplicationBuilder¶This class serves as initializer for telegram.ext.Application via the so called builder pattern. To build a telegram.ext.Application, one first initializes an instance of this class. Arguments for the telegram.ext.Application to build are then added by subsequently calling the methods of the builder. Finally, the telegram.ext.Application is built by calling build(). In the simplest case this can look like the following example.
Example
application = ApplicationBuilder().token("TOKEN").build()
Please see the description of the individual methods for information on which arguments can be set and what the defaults are when not called. When no default is mentioned, the argument will not be used by default.
Changed in version 22.0: Removed deprecated methods proxy_url and get_updates_proxy_url.
Sets a custom subclass instead of telegram.ext.Application. The subclass’s __init__ should look like this
def __init__(self, custom_arg_1, custom_arg_2, ..., **kwargs):
super().__init__(**kwargs)
self.custom_arg_1 = custom_arg_1
self.custom_arg_2 = custom_arg_2
application_class (type) – A subclass of telegram.ext.Application
kwargs (dict[str, object], optional) – Keyword arguments for the initialization. Defaults to an empty dict.
The same builder with the updated argument.
Specifies whether telegram.ext.Application.bot should allow arbitrary objects as callback data for telegram.InlineKeyboardButton and how many keyboards should be cached in memory. If not called, only strings can be used as callback data and no data will be stored in memory.
Important
If you want to use this feature, you must install PTB with the optional requirement callback-data, i.e.
pip install "python-telegram-bot[callback-data]"
arbitrary_callback_data (bool | int) – If True is passed, the default cache size of 1024 will be used. Pass an integer to specify a different cache size.
The same builder with the updated argument.
Sets the base file URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/file/bot'.
Changed in version 21.11: Supports callable input and string formatting.
base_file_url (str | Callable[[str], str]) – The URL or input for the URL as accepted by telegram.Bot.base_file_url.
The same builder with the updated argument.
Sets the base URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/bot'.
Changed in version 21.11: Supports callable input and string formatting.
base_url (str | Callable[[str], str]) – The URL or input for the URL as accepted by telegram.Bot.base_url.
The same builder with the updated argument.
Sets a telegram.Bot instance for telegram.ext.Application.bot. Instances of subclasses like telegram.ext.ExtBot are also valid.
bot (telegram.Bot) – The bot.
The same builder with the updated argument.
Builds a telegram.ext.Application with the provided arguments.
Calls telegram.ext.JobQueue.set_application() and telegram.ext.BasePersistence.set_bot() if appropriate.
Specifies if and how many updates may be processed concurrently instead of one by one. If not called, updates will be processed one by one.
Warning
Processing updates concurrently is not recommended when stateful handlers like telegram.ext.ConversationHandler are used. Only use this if you are sure that your bot does not (explicitly or implicitly) rely on updates being processed sequentially.
concurrent_updates (bool | int | BaseUpdateProcessor) –
Passing True will allow for 256 updates to be processed concurrently using telegram.ext.SimpleUpdateProcessor. Pass an integer to specify a different number of updates that may be processed concurrently. Pass an instance of telegram.ext.BaseUpdateProcessor to use that instance for handling updates concurrently.
Changed in version 20.4: Now accepts BaseUpdateProcessor instances.
The same builder with the updated argument.
Sets the connection attempt timeout for the connect_timeout parameter of telegram.Bot.request. Defaults to 5.0.
connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
The same builder with the updated argument.
Sets the size of the connection pool for the connection_pool_size parameter of telegram.Bot.request. Defaults to 256.
connection_pool_size (int) – The size of the connection pool.
The same builder with the updated argument.
Sets a telegram.ext.ContextTypes instance for telegram.ext.Application.context_types.
context_types (telegram.ext.ContextTypes) – The context types.
The same builder with the updated argument.
Sets the telegram.ext.Defaults instance for telegram.ext.Application.bot.
defaults (telegram.ext.Defaults) – The defaults instance.
The same builder with the updated argument.
Sets the connection attempt timeout for the telegram.request.HTTPXRequest.connect_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.
get_updates_connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
The same builder with the updated argument.
Sets the size of the connection pool for the telegram.request.HTTPXRequest.connection_pool_size parameter which is used for the telegram.Bot.get_updates() request. Defaults to 1.
get_updates_connection_pool_size (int) – The size of the connection pool.
The same builder with the updated argument.
Sets the HTTP protocol version which is used for the http_version parameter which is used in the telegram.Bot.get_updates() request. By default, HTTP/1.1 is used.
Note
Users have observed stability issues with HTTP/2, which happen due to how the h2 library handles cancellations of keepalive connections. See #3556 for a discussion.
You will also need to install the http2 dependency. Keep in mind that the HTTP/1.1 implementation may be considered the “more robust option at this time”.
Added in version 20.1.
Changed in version 20.2: Reset the default version to 1.1.
get_updates_http_version (str) –
Pass "2" or "2.0" if you’d like to use HTTP/2 for making requests to Telegram. Defaults to "1.1", in which case HTTP/1.1 is used.
Changed in version 20.5: Accept "2" as a valid value.
The same builder with the updated argument.
Sets the connection pool’s connection freeing timeout for the pool_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 1.0.
get_updates_pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
The same builder with the updated argument.
Sets the proxy for the telegram.request.HTTPXRequest.proxy parameter which is used for telegram.Bot.get_updates(). Defaults to None.
Added in version 20.7.
proxy (str | httpx.Proxy | httpx.URL) – The URL to a proxy server, a httpx.Proxy object or a httpx.URL object. See telegram.request.HTTPXRequest.proxy for more information.
The same builder with the updated argument.
Sets the waiting timeout for the telegram.request.HTTPXRequest.read_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.
get_updates_read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
The same builder with the updated argument.
Sets a telegram.request.BaseRequest instance for the get_updates_request parameter of telegram.ext.Application.bot.
get_updates_request (telegram.request.BaseRequest) – The request instance.
The same builder with the updated argument.
Sets the options for the socket_options parameter of telegram.Bot.get_updates_request. Defaults to None.
Added in version 20.7.
get_updates_socket_options (Collection[tuple], optional) – Socket options. See telegram.request.HTTPXRequest.socket_options for more information.
The same builder with the updated argument.
Sets the write operation timeout for the telegram.request.HTTPXRequest.write_timeout parameter which is used for the telegram.Bot.get_updates() request. Defaults to 5.0.
get_updates_write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
The same builder with the updated argument.
Sets the HTTP protocol version which is used for the http_version parameter of telegram.Bot.request. By default, HTTP/1.1 is used.
Note
Users have observed stability issues with HTTP/2, which happen due to how the h2 library handles cancellations of keepalive connections. See #3556 for a discussion.
If you want to use HTTP/2, you must install PTB with the optional requirement http2, i.e.
pip install "python-telegram-bot[http2]"
Keep in mind that the HTTP/1.1 implementation may be considered the “more robust option at this time”.
Added in version 20.1.
Changed in version 20.2: Reset the default version to 1.1.
http_version (str) –
Pass "2" or "2.0" if you’d like to use HTTP/2 for making requests to Telegram. Defaults to "1.1", in which case HTTP/1.1 is used.
Changed in version 20.5: Accept "2" as a valid value.
The same builder with the updated argument.
Sets a telegram.ext.JobQueue instance for telegram.ext.Application.job_queue. If not called, a job queue will be instantiated if the requirements of telegram.ext.JobQueue are installed.
job_queue (telegram.ext.JobQueue) – The job queue. Pass None if you don’t want to use a job queue.
The same builder with the updated argument.
Specifies the value for local_mode for the telegram.ext.Application.bot. If not called, will default to False.
local_mode (bool) – Whether the bot should run in local mode.
The same builder with the updated argument.
Sets the media write operation timeout for the media_write_timeout parameter of telegram.Bot.request. Defaults to 20.
Added in version 21.0.
media_write_timeout (float) – See telegram.request.HTTPXRequest.media_write_timeout for more information.
The same builder with the updated argument.
Sets a telegram.ext.BasePersistence instance for telegram.ext.Application.persistence.
persistence (telegram.ext.BasePersistence) – The persistence instance.
The same builder with the updated argument.
Sets the connection pool’s connection freeing timeout for the pool_timeout parameter of telegram.Bot.request. Defaults to 1.0.
pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
The same builder with the updated argument.
Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Application.initialize() but before executing Updater.start_polling() or Updater.start_webhook(), respectively.
Tip
This can be used for custom startup logic that requires to await coroutines, e.g. setting up the bots commands via set_my_commands().
Example
async def post_init(application: Application) -> None:
await application.bot.set_my_commands([('start', 'Starts the bot')])
application = Application.builder().token("TOKEN").post_init(post_init).build()
Note
If you implement custom logic that implies that you will not be using Application’s methods run_polling() or run_webhook() to run your application (like it’s done in Custom Webhook Bot Example), the callback you set in this method will not be called automatically. So instead of setting a callback with this method, you have to explicitly await the function that you want to run at this stage of your application’s life (in the example mentioned above, that would be in async with application context manager).
post_init (coroutine function) –
The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:
async def post_init(application: Application) -> None:
The same builder with the updated argument.
Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Updater.shutdown() and Application.shutdown().
Tip
This can be used for custom shutdown logic that requires to await coroutines, e.g. closing a database connection
Example
async def post_shutdown(application: Application) -> None:
await application.bot_data['database'].close()
application = Application.builder()
.token("TOKEN")
.post_shutdown(post_shutdown)
.build()
Note
If you implement custom logic that implies that you will not be using Application’s methods run_polling() or run_webhook() to run your application (like it’s done in Custom Webhook Bot Example), the callback you set in this method will not be called automatically. So instead of setting a callback with this method, you have to explicitly await the function that you want to run at this stage of your application’s life (in the example mentioned above, that would be in async with application context manager).
post_shutdown (coroutine function) –
The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:
async def post_shutdown(application: Application) -> None:
The same builder with the updated argument.
Sets a callback to be executed by Application.run_polling() and Application.run_webhook() after executing Updater.stop() and Application.stop().
Added in version 20.1.
Tip
This can be used for custom stop logic that requires to await coroutines, e.g. sending message to a chat before shutting down the bot.
Example
async def post_stop(application: Application) -> None:
await application.bot.send_message(123456, "Shutting down...")
application = Application.builder()
.token("TOKEN")
.post_stop(post_stop)
.build()
Note
If you implement custom logic that implies that you will not be using Application’s methods run_polling() or run_webhook() to run your application (like it’s done in Custom Webhook Bot Example), the callback you set in this method will not be called automatically. So instead of setting a callback with this method, you have to explicitly await the function that you want to run at this stage of your application’s life (in the example mentioned above, that would be in async with application context manager).
post_stop (coroutine function) –
The custom callback. Must be a coroutine function and must accept exactly one positional argument, which is the Application:
async def post_stop(application: Application) -> None:
The same builder with the updated argument.
Sets the private key and corresponding password for decryption of telegram passport data for telegram.ext.Application.bot.
private_key (bytes | str | pathlib.Path) – The private key or the file path of a file that contains the key. In the latter case, the file’s content will be read automatically.
password (bytes | str | pathlib.Path, optional) – The corresponding password or the file path of a file that contains the password. In the latter case, the file’s content will be read automatically.
The same builder with the updated argument.
Sets the proxy for the proxy parameter of telegram.Bot.request. Defaults to None.
Added in version 20.7.
proxy (str | httpx.Proxy | httpx.URL) – The URL to a proxy server, a httpx.Proxy object or a httpx.URL object. See telegram.request.HTTPXRequest.proxy for more information.
The same builder with the updated argument.
Sets a telegram.ext.BaseRateLimiter instance for the telegram.ext.ExtBot.rate_limiter parameter of telegram.ext.Application.bot.
rate_limiter (telegram.ext.BaseRateLimiter) – The rate limiter.
The same builder with the updated argument.
Sets the waiting timeout for the read_timeout parameter of telegram.Bot.request. Defaults to 5.0.
read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
The same builder with the updated argument.
Sets a telegram.request.BaseRequest instance for the telegram.Bot.request parameter of telegram.ext.Application.bot.
request (telegram.request.BaseRequest) – The request instance.
The same builder with the updated argument.
Sets the options for the socket_options parameter of telegram.Bot.request. Defaults to None.
Added in version 20.7.
socket_options (Collection[tuple], optional) – Socket options. See telegram.request.HTTPXRequest.socket_options for more information.
The same builder with the updated argument.
Sets the token for telegram.ext.Application.bot.
The same builder with the updated argument.
Sets a asyncio.Queue instance for telegram.ext.Application.update_queue, i.e. the queue that the application will fetch updates from. Will also be used for the telegram.ext.Application.updater. If not called, a queue will be instantiated.
update_queue (asyncio.Queue) – The queue.
The same builder with the updated argument.
Sets a telegram.ext.Updater instance for telegram.ext.Application.updater. The telegram.ext.Updater.bot and telegram.ext.Updater.update_queue will be used for telegram.ext.Application.bot and telegram.ext.Application.update_queue, respectively.
updater (telegram.ext.Updater | None) – The updater instance or None if no updater should be used.
The same builder with the updated argument.
Sets the write operation timeout for the write_timeout parameter of telegram.Bot.request. Defaults to 5.0.
write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
The same builder with the updated argument.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4