telegram.ext.ApplicationBuilder#

class telegram.ext.ApplicationBuilder[source]#

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.

Note

Some arguments are mutually exclusive. E.g. after calling token(), you can’t set a custom bot with bot() and vice versa.
Unless a custom telegram.Bot instance is set via bot(), build() will use telegram.ext.ExtBot for the bot.

application_class(application_class, kwargs=None)[source]#

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

Parameters

application_class (type) – A subclass of telegram.ext.Application
kwargs (Dict[str, object], optional) – Keyword arguments for the initialization. Defaults to an empty dict.

Returns

The same builder with the updated argument.

Return type

ApplicationBuilder

arbitrary_callback_data(arbitrary_callback_data)[source]#

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.

Parameters: 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.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

base_file_url(base_file_url)[source]#

Sets the base file URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/file/bot'.

Parameters: base_file_url (str) – The URL.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

base_url(base_url)[source]#

Sets the base URL for telegram.ext.Application.bot. If not called, will default to 'https://api.telegram.org/bot'.

Parameters: base_url (str) – The URL.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

bot(bot)[source]#

Sets a telegram.Bot instance for telegram.ext.Application.bot. Instances of subclasses like telegram.ext.ExtBot are also valid.

Parameters: bot (telegram.Bot) – The bot.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

build()[source]#

Builds a telegram.ext.Application with the provided arguments.

Calls telegram.ext.JobQueue.set_application() and telegram.ext.BasePersistence.set_bot() if appropriate.

Returns: telegram.ext.Application

concurrent_updates(concurrent_updates)[source]#

Specifies if and how many updates may be processed concurrently instead of 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.

Parameters: concurrent_updates (bool | int) – Passing True will allow for 4096 updates to be processed concurrently. Pass an integer to specify a different number of updates that may be processed concurrently.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

connect_timeout(connect_timeout)[source]#

Sets the connection attempt timeout for the connect_timeout parameter of telegram.Bot.request. Defaults to 5.0.

Parameters: connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

connection_pool_size(connection_pool_size)[source]#

Sets the size of the connection pool for the connection_pool_size parameter of telegram.Bot.request. Defaults to 128.

Parameters: connection_pool_size (int) – The size of the connection pool.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

context_types(context_types)[source]#

Sets a telegram.ext.ContextTypes instance for telegram.ext.Application.context_types.

See also

contexttypesbot.py

Parameters: context_types (telegram.ext.ContextTypes) – The context types.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

defaults(defaults)[source]#

Sets the telegram.ext.Defaults instance for telegram.ext.Application.bot.

See also

Adding Defaults

Parameters: defaults (telegram.ext.Defaults) – The defaults instance.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_connect_timeout(get_updates_connect_timeout)[source]#

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.

Parameters: get_updates_connect_timeout (float) – See telegram.request.HTTPXRequest.connect_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_connection_pool_size(get_updates_connection_pool_size)[source]#

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.

Parameters: get_updates_connection_pool_size (int) – The size of the connection pool.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_pool_timeout(get_updates_pool_timeout)[source]#

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 None.

Parameters: get_updates_pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_proxy_url(get_updates_proxy_url)[source]#

Sets the proxy for the telegram.request.HTTPXRequest.proxy_url parameter which is used for telegram.Bot.get_updates(). Defaults to None.

Parameters: get_updates_proxy_url (str) – The URL to the proxy server. See telegram.request.HTTPXRequest.proxy_url for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_read_timeout(get_updates_read_timeout)[source]#

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.

Parameters: get_updates_read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_request(get_updates_request)[source]#

Sets a telegram.request.BaseRequest instance for the get_updates_request parameter of telegram.ext.Application.bot.

See also

request()

Parameters: get_updates_request (telegram.request.BaseRequest) – The request instance.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

get_updates_write_timeout(get_updates_write_timeout)[source]#

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.

Parameters: get_updates_write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

job_queue(job_queue)[source]#

Sets a telegram.ext.JobQueue instance for telegram.ext.Application.job_queue. If not called, a job queue will be instantiated.

See also

JobQueue, timerbot.py

Note

telegram.ext.JobQueue.set_application() will be called automatically by build().
The job queue will be automatically started and stopped by telegram.ext.Application.start() and telegram.ext.Application.stop(), respectively.
When passing None, telegram.ext.ConversationHandler.conversation_timeout can not be used, as this uses telegram.ext.Application.job_queue internally.

Parameters: job_queue (telegram.ext.JobQueue) – The job queue. Pass None if you don’t want to use a job queue.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

persistence(persistence)[source]#

Sets a telegram.ext.BasePersistence instance for telegram.ext.Application.persistence.

Note

When using a persistence, note that all data stored in context.user_data, context.chat_data, context.bot_data and in telegram.ext.ExtBot.callback_data_cache must be copyable with copy.deepcopy(). This is due to the data being deep copied before handing it over to the persistence in order to avoid race conditions.

Warning

If a telegram.ext.ContextTypes instance is set via context_types(), the persistence instance must use the same types!

Parameters: persistence (telegram.ext.BasePersistence) – The persistence instance.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

pool_timeout(pool_timeout)[source]#

Sets the connection pool’s connection freeing timeout for the pool_timeout parameter of telegram.Bot.request. Defaults to None.

Parameters: pool_timeout (float) – See telegram.request.HTTPXRequest.pool_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

private_key(private_key, password=None)[source]#

Sets the private key and corresponding password for decryption of telegram passport data for telegram.ext.Application.bot.

See also

passportbot.py, Telegram Passports

Parameters

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.

Returns

The same builder with the updated argument.

Return type

ApplicationBuilder

proxy_url(proxy_url)[source]#

Sets the proxy for the proxy_url parameter of telegram.Bot.request. Defaults to None.

Parameters: proxy_url (str) – The URL to the proxy server. See telegram.request.HTTPXRequest.proxy_url for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

read_timeout(read_timeout)[source]#

Sets the waiting timeout for the read_timeout parameter of telegram.Bot.request. Defaults to 5.0.

Parameters: read_timeout (float) – See telegram.request.HTTPXRequest.read_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

request(request)[source]#

Sets a telegram.request.BaseRequest instance for the telegram.Bot.request parameter of telegram.ext.Application.bot.

See also

get_updates_request()

Parameters: request (telegram.request.BaseRequest) – The request instance.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

token(token)[source]#

Sets the token for telegram.ext.Application.bot.

Parameters: token (str) – The token.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

update_queue(update_queue)[source]#

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.

See also

telegram.ext.Updater.update_queue

Parameters: update_queue (asyncio.Queue) – The queue.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

updater(updater)[source]#

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.

Parameters: updater (telegram.ext.Updater | None) – The updater instance or None if no updater should be used.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder

write_timeout(write_timeout)[source]#

Sets the write operation timeout for the write_timeout parameter of telegram.Bot.request. Defaults to 5.0.

Parameters: write_timeout (float) – See telegram.request.HTTPXRequest.write_timeout for more information.
Returns: The same builder with the updated argument.
Return type: ApplicationBuilder