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 atelegram.ext.Application
, one first initializes an instance of this class. Arguments for thetelegram.ext.Application
to build are then added by subsequently calling the methods of the builder. Finally, thetelegram.ext.Application
is built by callingbuild()
. 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 withbot()
and vice versa.Unless a custom
telegram.Bot
instance is set viabot()
,build()
will usetelegram.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 thisdef __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 oftelegram.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
- arbitrary_callback_data(arbitrary_callback_data)[source]¶
Specifies whether
telegram.ext.Application.bot
should allow arbitrary objects as callback data fortelegram.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]
- Parameters
arbitrary_callback_data (
bool
|int
) – IfTrue
is passed, the default cache size of1024
will be used. Pass an integer to specify a different cache size.- Returns
The same builder with the updated argument.
- Return type
- 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
- 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
- Returns
The same builder with the updated argument.
- Return type
- bot(bot)[source]¶
Sets a
telegram.Bot
instance fortelegram.ext.Application.bot
. Instances of subclasses liketelegram.ext.ExtBot
are also valid.- Parameters
bot (
telegram.Bot
) – The bot.- Returns
The same builder with the updated argument.
- Return type
- build()[source]¶
Builds a
telegram.ext.Application
with the provided arguments.Calls
telegram.ext.JobQueue.set_application()
andtelegram.ext.BasePersistence.set_bot()
if appropriate.- Returns
- 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.Tip
When making requests to the Bot API in an asynchronous fashion (e.g. via
block=False
,Application.create_task
,concurrent_updates()
or theJobQueue
), it can happen that more requests are being made in parallel than there are connections in the pool. If the number of requests is much higher than the number of connections, even settingpool_timeout()
to a larger value may not always be enough to prevent pool timeouts. You should therefore setconcurrent_updates()
,connection_pool_size()
andpool_timeout()
to values that make sense for your setup.- Parameters
concurrent_updates (
bool
|int
) – PassingTrue
will allow for256
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
- connect_timeout(connect_timeout)[source]¶
Sets the connection attempt timeout for the
connect_timeout
parameter oftelegram.Bot.request
. Defaults to5.0
.- Parameters
connect_timeout (
float
) – Seetelegram.request.HTTPXRequest.connect_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- connection_pool_size(connection_pool_size)[source]¶
Sets the size of the connection pool for the
connection_pool_size
parameter oftelegram.Bot.request
. Defaults to256
.- Parameters
connection_pool_size (
int
) – The size of the connection pool.- Returns
The same builder with the updated argument.
- Return type
- context_types(context_types)[source]¶
Sets a
telegram.ext.ContextTypes
instance fortelegram.ext.Application.context_types
.See also
- Parameters
context_types (
telegram.ext.ContextTypes
) – The context types.- Returns
The same builder with the updated argument.
- Return type
- defaults(defaults)[source]¶
Sets the
telegram.ext.Defaults
instance fortelegram.ext.Application.bot
.See also
- Parameters
defaults (
telegram.ext.Defaults
) – The defaults instance.- Returns
The same builder with the updated argument.
- Return type
- 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 thetelegram.Bot.get_updates()
request. Defaults to5.0
.- Parameters
get_updates_connect_timeout (
float
) – Seetelegram.request.HTTPXRequest.connect_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- 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 thetelegram.Bot.get_updates()
request. Defaults to1
.- Parameters
get_updates_connection_pool_size (
int
) – The size of the connection pool.- Returns
The same builder with the updated argument.
- Return type
- 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 thetelegram.Bot.get_updates()
request. Defaults toNone
.- Parameters
get_updates_pool_timeout (
float
) – Seetelegram.request.HTTPXRequest.pool_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- get_updates_proxy_url(get_updates_proxy_url)[source]¶
Sets the proxy for the
telegram.request.HTTPXRequest.proxy_url
parameter which is used fortelegram.Bot.get_updates()
. Defaults toNone
.- Parameters
get_updates_proxy_url (
str
) – The URL to the proxy server. Seetelegram.request.HTTPXRequest.proxy_url
for more information.- Returns
The same builder with the updated argument.
- Return type
- 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 thetelegram.Bot.get_updates()
request. Defaults to5.0
.- Parameters
get_updates_read_timeout (
float
) – Seetelegram.request.HTTPXRequest.read_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- get_updates_request(get_updates_request)[source]¶
Sets a
telegram.request.BaseRequest
instance for theget_updates_request
parameter oftelegram.ext.Application.bot
.See also
- Parameters
get_updates_request (
telegram.request.BaseRequest
) – The request instance.- Returns
The same builder with the updated argument.
- Return type
- 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 thetelegram.Bot.get_updates()
request. Defaults to5.0
.- Parameters
get_updates_write_timeout (
float
) – Seetelegram.request.HTTPXRequest.write_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- job_queue(job_queue)[source]¶
Sets a
telegram.ext.JobQueue
instance fortelegram.ext.Application.job_queue
. If not called, a job queue will be instantiated if the requirements oftelegram.ext.JobQueue
are installed.See also
Note
telegram.ext.JobQueue.set_application()
will be called automatically bybuild()
.The job queue will be automatically started and stopped by
telegram.ext.Application.start()
andtelegram.ext.Application.stop()
, respectively.When passing
None
or when the requirements oftelegram.ext.JobQueue
are not installed,telegram.ext.ConversationHandler.conversation_timeout
can not be used, as this usestelegram.ext.Application.job_queue
internally.
- Parameters
job_queue (
telegram.ext.JobQueue
) – The job queue. PassNone
if you don’t want to use a job queue.- Returns
The same builder with the updated argument.
- Return type
- local_mode(local_mode)[source]¶
- Specifies the value for
local_mode
for the telegram.ext.Application.bot
. If not called, will default toFalse
.
See also
- Parameters
local_mode (
bool
) – Whether the bot should run in local mode.- Returns
The same builder with the updated argument.
- Return type
- Specifies the value for
- persistence(persistence)[source]¶
Sets a
telegram.ext.BasePersistence
instance fortelegram.ext.Application.persistence
.Note
When using a persistence, note that all data stored in
context.user_data
,context.chat_data
,context.bot_data
and intelegram.ext.ExtBot.callback_data_cache
must be copyable withcopy.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 viacontext_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
- pool_timeout(pool_timeout)[source]¶
Sets the connection pool’s connection freeing timeout for the
pool_timeout
parameter oftelegram.Bot.request
. Defaults toNone
.- Parameters
pool_timeout (
float
) – Seetelegram.request.HTTPXRequest.pool_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- post_init(post_init)[source]¶
Sets a callback to be executed by
Application.run_polling()
andApplication.run_webhook()
after executingApplication.initialize()
but before executingUpdater.start_polling()
orUpdater.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()
- Parameters
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:
- Returns
The same builder with the updated argument.
- Return type
- post_shutdown(post_shutdown)[source]¶
Sets a callback to be executed by
Application.run_polling()
andApplication.run_webhook()
after executingUpdater.shutdown()
andApplication.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()
- Parameters
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:
- Returns
The same builder with the updated argument.
- Return type
- 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
- 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
- proxy_url(proxy_url)[source]¶
Sets the proxy for the
proxy_url
parameter oftelegram.Bot.request
. Defaults toNone
.- Parameters
proxy_url (
str
) – The URL to the proxy server. Seetelegram.request.HTTPXRequest.proxy_url
for more information.- Returns
The same builder with the updated argument.
- Return type
- rate_limiter(rate_limiter)[source]¶
Sets a
telegram.ext.BaseRateLimiter
instance for thetelegram.ext.ExtBot.rate_limiter
parameter oftelegram.ext.Application.bot
.- Parameters
rate_limiter (
telegram.ext.BaseRateLimiter
) – The rate limiter.- Returns
The same builder with the updated argument.
- Return type
- read_timeout(read_timeout)[source]¶
Sets the waiting timeout for the
read_timeout
parameter oftelegram.Bot.request
. Defaults to5.0
.- Parameters
read_timeout (
float
) – Seetelegram.request.HTTPXRequest.read_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type
- request(request)[source]¶
Sets a
telegram.request.BaseRequest
instance for thetelegram.Bot.request
parameter oftelegram.ext.Application.bot
.See also
- Parameters
request (
telegram.request.BaseRequest
) – The request instance.- Returns
The same builder with the updated argument.
- Return type
- token(token)[source]¶
Sets the token for
telegram.ext.Application.bot
.- Parameters
- Returns
The same builder with the updated argument.
- Return type
- update_queue(update_queue)[source]¶
Sets a
asyncio.Queue
instance fortelegram.ext.Application.update_queue
, i.e. the queue that the application will fetch updates from. Will also be used for thetelegram.ext.Application.updater
. If not called, a queue will be instantiated.See also
- Parameters
update_queue (
asyncio.Queue
) – The queue.- Returns
The same builder with the updated argument.
- Return type
- updater(updater)[source]¶
Sets a
telegram.ext.Updater
instance fortelegram.ext.Application.updater
. Thetelegram.ext.Updater.bot
andtelegram.ext.Updater.update_queue
will be used fortelegram.ext.Application.bot
andtelegram.ext.Application.update_queue
, respectively.- Parameters
updater (
telegram.ext.Updater
|None
) – The updater instance orNone
if no updater should be used.- Returns
The same builder with the updated argument.
- Return type
- write_timeout(write_timeout)[source]¶
Sets the write operation timeout for the
write_timeout
parameter oftelegram.Bot.request
. Defaults to5.0
.- Parameters
write_timeout (
float
) – Seetelegram.request.HTTPXRequest.write_timeout
for more information.- Returns
The same builder with the updated argument.
- Return type