JobQueue¶
class telegram.ext. JobQueue [source] ¶ Bases: typing.Generic This class allows you to periodically perform tasks with the bot. It is a convenience wrapper for the APScheduler library. This class is a Generic class and accepts one type variable that specifies the type of the argument context of the job callbacks ( callback ) of run_once() and the other scheduling methods.
Important If you want to use this class, you must install PTB with the optional requirement job-queue , i.e.
pip install "python-telegram-bot[job-queue]" Changed in version 20.0: To use this class, PTB must be installed via pip install «python-telegram-bot[job-queue]» .
Changed in version 20.0: Uses AsyncIOScheduler instead of BackgroundScheduler
The application this JobQueue is associated with.
Returns a tuple of all pending/scheduled jobs with the given name that are currently in the JobQueue .
Tuple of all pending or scheduled jobs matching the name.
async static job_callback ( job_queue , job ) [source] ¶
This method is used as a callback for the APScheduler jobs.
More precisely, the func argument of apscheduler.job.Job is set to this method and the arg argument (representing positional arguments to func ) is set to a tuple containing the JobQueue itself and the Job instance.
This method is a static method rather than a bound method. This makes the arguments more transparent and allows for easier handling of PTBs integration of APScheduler when utilizing advanced features of APScheduler.
This method is effectively a wrapper for telegram.ext.Job.run() .
Returns a tuple of all scheduled jobs that are currently in the JobQueue .
Tuple of all scheduled jobs.
run_custom ( callback , job_kwargs , data = None , name = None , chat_id = None , user_id = None ) [source] ¶
Creates a new custom defined Job .
- callback ( coroutine function ) – The callback function that should be executed by the new job. Callback signature:
async def callback(context: CallbackContext)
The new Job instance that has been added to the job queue.
run_daily ( callback , time , days = (0, 1, 2, 3, 4, 5, 6) , data = None , name = None , chat_id = None , user_id = None , job_kwargs = None ) [source] ¶
Creates a new Job that runs on a daily basis and adds it to the queue.
For a note about DST, please see the documentation of APScheduler.
async def callback(context: CallbackContext)
Changed in version 20.0: Changed day of the week mapping of 0-6 from monday-sunday to sunday-saturday.
The new Job instance that has been added to the job queue.
run_monthly ( callback , when , day , data = None , name = None , chat_id = None , user_id = None , job_kwargs = None ) [source] ¶
Creates a new Job that runs on a monthly basis and adds it to the queue.
Changed in version 20.0: The day_is_strict argument was removed. Instead one can now pass -1 to the day parameter to have the job run on the last day of the month.
async def callback(context: CallbackContext)
The new Job instance that has been added to the job queue.
run_once ( callback , when , data = None , name = None , chat_id = None , user_id = None , job_kwargs = None ) [source] ¶
Creates a new Job instance that runs once and adds it to the queue.
- callback ( coroutine function ) – The callback function that should be executed by the new job. Callback signature:
async def callback(context: CallbackContext)
- int or float will be interpreted as “seconds from now” in which the job should run.
- datetime.timedelta will be interpreted as “time from now” in which the job should run.
- datetime.datetime will be interpreted as a specific date and time at which the job should run. If the timezone ( datetime.datetime.tzinfo ) is None , the default timezone of the bot will be used, which is UTC unless telegram.ext.Defaults.tzinfo is used.
- datetime.time will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, tomorrow. If the timezone ( datetime.time.tzinfo ) is None , the default timezone of the bot will be used, which is UTC unless telegram.ext.Defaults.tzinfo is used.
The new Job instance that has been added to the job queue.
run_repeating ( callback , interval , first = None , last = None , data = None , name = None , chat_id = None , user_id = None , job_kwargs = None ) [source] ¶
Creates a new Job instance that runs at specified intervals and adds it to the queue.
For a note about DST, please see the documentation of APScheduler.
async def callback(context: CallbackContext)
- int or float will be interpreted as “seconds from now” in which the job should run.
- datetime.timedelta will be interpreted as “time from now” in which the job should run.
- datetime.datetime will be interpreted as a specific date and time at which the job should run. If the timezone ( datetime.datetime.tzinfo ) is None , the default timezone of the bot will be used.
- datetime.time will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, tomorrow. If the timezone ( datetime.time.tzinfo ) is None , the default timezone of the bot will be used, which is UTC unless telegram.ext.Defaults.tzinfo is used.
Setting first to 0 , datetime.datetime.now() or another value that indicates that the job should run immediately will not work due to how the APScheduler library works. If you want to run a job immediately, we recommend to use an approach along the lines of:
job = context.job_queue.run_repeating(callback, interval=5) await job.run(context.application)
Introduction#
This library provides a pure Python, asynchronous interface for the Telegram Bot API. It’s compatible with Python versions 3.7+. In addition to the pure API implementation, this library features a number of high-level classes to make the development of bots easy and straightforward. These classes are contained in the telegram.ext submodule. A pure API implementation without telegram.ext is available as the standalone package python-telegram-bot-raw . See here for details.
Note#
Installing both python-telegram-bot and python-telegram-bot-raw in conjunction will result in undesired side-effects, so only install one of both.
Telegram API support#
Installing#
$ pip install python-telegram-bot --upgrade
To install a pre-release, use the —pre flag in addition. You can also install python-telegram-bot from source, though this is usually not necessary.
$ git clone https://github.com/python-telegram-bot/python-telegram-bot $ cd python-telegram-bot $ python setup.py install Dependencies & Their Versions#
- httpx ~= 0.22.0 for telegram.request.HTTPXRequest , the default networking backend
- tornado~=6.1 for telegram.ext.Updater.start_webhook
- cachetools~=5.0.0 for telegram.ext.CallbackDataCache
- APScheduler~=3.9.1 for telegram.ext.JobQueue
python-telegram-bot is most useful when used along with additional libraries. To minimize dependency conflicts, we try to be liberal in terms of version requirements on the dependencies. On the other hand, we have to ensure stability of python-telegram-bot , which is why we do apply version bounds. If you encounter dependency conflicts due to these bounds, feel free to reach out.
Optional Dependencies#
PTB can be installed with optional dependencies:
- pip install python-telegram-bot[passport] installs the cryptography>=3.0 library. Use this, if you want to use Telegram Passport related functionality.
- pip install python-telegram-bot[json] installs the ujson>=4.0.0 library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard json library.
- pip install python-telegram-bot[socks] installs httpx[socks] . Use this, if you want to work behind a Socks5 server.
Quick Start#
Our Wiki contains an Introduction to the API explaining how the pure Bot API can be accessed via python-telegram-bot . Moreover, the Tutorial: Your first Bot gives an introduction on how chatbots can be easily programmed with the help of the telegram.ext module.
Resources#
- The package documentation is the technical reference for python-telegram-bot . It contains descriptions of all available classes, modules, methods and arguments.
- The wiki is home to number of more elaborate introductions of the different features of python-telegram-bot and other useful resources that go beyond the technical documentation.
- Our examples directory contains several examples that showcase the different features of both the Bot API and python-telegram-bot . Even if it is not your approach for learning, please take a look at echobot.py . It is the de facto base for most of the bots out there. The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it.
- The official Telegram Bot API documentation is of course always worth a read.
Getting help#
If the resources mentioned above don’t answer your questions or simply overwhelm you, there are several ways of getting help.
- We have a vibrant community of developers helping each other in our Telegram group. Join us! Asking a question here is often the quickest way to get a pointer in the right direction.
- Ask questions by opening a discussion.
- You can even ask for help on Stack Overflow using the python-telegram-bot tag.
Concurrency#
Since v20.0, python-telegram-bot is built on top of Pythons asyncio module. Because asyncio is in general single-threaded, python-telegram-bot does currently not aim to be thread-safe. Noteworthy parts of python-telegram-bots API that are likely to cause issues (e.g. race conditions) when used in a multi-threaded setting include:
- telegram.ext.Application/Updater.update_queue
- telegram.ext.ConversationHandler.check/handle_update
- telegram.ext.CallbackDataCache
- telegram.ext.BasePersistence
- all classes in the telegram.ext.filters module that allow to add/remove allowed users/chats at runtime
Contributing#
Contributions of all sizes are welcome. Please review our contribution guidelines to get started. You can also help by reporting bugs or feature requests.
Donating#
Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
License#
You may copy, distribute and modify the software provided that modifications are described and licensed for free under LGPL-3. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don’t have to be.