Skip to content
Back to top
View this page

# JobQueue

class telegram.ext.JobQueue

  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]"

  Examples

  Timer Bot

  See also

  Architecture Overview, Job Queue

  Use In

  `telegram.ext.ApplicationBuilder.job_queue()`

  Available In

  - `telegram.ext.Application.job_queue`

  - `telegram.ext.CallbackContext.job_queue`

  - `telegram.ext.JobQueue.application`

  Returned In

  `telegram.ext.Application.builder()`

  Changed in version 20.0: To use this class, PTB must be installed via `pip install "python-telegram-bot[job-queue]"`.

  scheduler

    The scheduler.

    Warning

    This scheduler is configured by `set_application()`. Additional configuration settings can be made by users. However, calling `configure()` will delete any previous configuration settings. Therefore, please make sure to pass the values returned by `scheduler_configuration` to the method call in addition to your custom values. Alternatively, you can also use methods like `add_jobstore()` to avoid using `configure()` altogether.

    Changed in version 20.0: Uses `AsyncIOScheduler` instead of `BackgroundScheduler`

    Type:

      `apscheduler.schedulers.asyncio.AsyncIOScheduler`

  __repr__()

    Give a string representation of the JobQueue in the form `JobQueue[application=...]`.

    As this class doesn’t implement `object.__str__()`, the default implementation will be used, which is equivalent to `__repr__()`.

    Returns:

      `str`

  property application

    The application this JobQueue is associated with.

  get_jobs_by_name(name)

    Returns a tuple of all scheduled jobs with the given name that are currently in the `JobQueue`.

    Hint

    This method is a convenience wrapper for `jobs()` with a pattern that matches the given name.

    Returns:

      Tuple of all scheduled jobs matching the name.

    Return type:

      tuple[`Job`]

  async static job_callback(job_queue, job)

    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.

    Tip

    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.

    Hint

    This method is effectively a wrapper for `telegram.ext.Job.run()`.

    Added in version 20.4.

    Parameters:

      - job_queue (`JobQueue`) – The job queue that created the job.

      - job (`Job`) – The job to run.

  jobs(pattern=None)

    Returns a tuple of all scheduled jobs that are currently in the `JobQueue`.

    Parameters:

      pattern (`str` | `re.Pattern`, optional) –

      A regular expression pattern. If passed, only jobs whose name matches the pattern will be returned. Defaults to `None`.

      Hint

      This uses `re.search()` and not `re.match()`.

      Added in version 21.10.

    Returns:

      Tuple of all scheduled jobs.

    Return type:

      tuple[`Job`]

  run_custom(callback, job_kwargs, data=None, name=None, chat_id=None, user_id=None)

    Creates a new custom defined `Job`.

    Parameters:

      - callback (coroutine function) –

        The callback function that should be executed by the new job. Callback signature:

            async def callback(context: CallbackContext)

      - job_kwargs (`dict`) – Arbitrary keyword arguments. Used as arguments for `apscheduler.schedulers.base.BaseScheduler.add_job()`.

      - data (`object`, optional) –

        Additional data needed for the callback function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

        Changed in version 20.0: Renamed the parameter `context` to `data`.

      - name (`str`, optional) – The name of the new job. Defaults to `callback.__name__`.

      - chat_id (`int`, optional) –

        Chat id of the chat associated with this job. If passed, the corresponding `chat_data` will be available in the callback.

        Added in version 20.0.

      - user_id (`int`, optional) –

        User id of the user associated with this job. If passed, the corresponding `user_data` will be available in the callback.

        Added in version 20.0.

    Returns:

      The new `Job` instance that has been added to the job queue.

    Return type:

      `telegram.ext.Job`

  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)

    Creates a new `Job` that runs on a daily basis and adds it to the queue.

    Note

    For a note about DST, please see the documentation of APScheduler.

    Parameters:

      - callback (coroutine function) –

        The callback function that should be executed by the new job. Callback signature:

            async def callback(context: CallbackContext)

      - time (`datetime.time`) – Time of day at which the job should run. 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.

      - days (tuple[`int`], optional) –

        Defines on which days of the week the job should run (where `0-6` correspond to sunday - saturday). By default, the job will run every day.

        Changed in version 20.0: Changed day of the week mapping of 0-6 from monday-sunday to sunday-saturday.

      - data (`object`, optional) –

        Additional data needed for the callback function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

        Changed in version 20.0: Renamed the parameter `context` to `data`.

      - name (`str`, optional) – The name of the new job. Defaults to `callback.__name__`.

      - chat_id (`int`, optional) –

        Chat id of the chat associated with this job. If passed, the corresponding `chat_data` will be available in the callback.

        Added in version 20.0.

      - user_id (`int`, optional) –

        User id of the user associated with this job. If passed, the corresponding `user_data` will be available in the callback.

        Added in version 20.0.

      - job_kwargs (`dict`, optional) – Arbitrary keyword arguments to pass to the `apscheduler.schedulers.base.BaseScheduler.add_job()`.

    Returns:

      The new `Job` instance that has been added to the job queue.

    Return type:

      `telegram.ext.Job`

  run_monthly(callback, when, day, data=None, name=None, chat_id=None, user_id=None, job_kwargs=None)

    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.

    Parameters:

      - callback (coroutine function) –

        The callback function that should be executed by the new job. Callback signature:

            async def callback(context: CallbackContext)

      - when (`datetime.time`) – Time of day at which the job should run. If the timezone (`when.tzinfo`) is `None`, the default timezone of the bot will be used, which is UTC unless `telegram.ext.Defaults.tzinfo` is used.

      - day (`int`) – Defines the day of the month whereby the job would run. It should be within the range of `1` and `31`, inclusive. If a month has fewer days than this number, the job will not run in this month. Passing `-1` leads to the job running on the last day of the month.

      - data (`object`, optional) –

        Additional data needed for the callback function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

        Changed in version 20.0: Renamed the parameter `context` to `data`.

      - name (`str`, optional) – The name of the new job. Defaults to `callback.__name__`.

      - chat_id (`int`, optional) –

        Chat id of the chat associated with this job. If passed, the corresponding `chat_data` will be available in the callback.

        Added in version 20.0.

      - user_id (`int`, optional) –

        User id of the user associated with this job. If passed, the corresponding `user_data` will be available in the callback.

        Added in version 20.0.

      - job_kwargs (`dict`, optional) – Arbitrary keyword arguments to pass to the `apscheduler.schedulers.base.BaseScheduler.add_job()`.

    Returns:

      The new `Job` instance that has been added to the job queue.

    Return type:

      `telegram.ext.Job`

  run_once(callback, when, data=None, name=None, chat_id=None, user_id=None, job_kwargs=None)

    Creates a new `Job` instance that runs once and adds it to the queue.

    Parameters:

      - callback (coroutine function) –

        The callback function that should be executed by the new job. Callback signature:

            async def callback(context: CallbackContext)

      - when (`int` | `float` | `datetime.timedelta` | `datetime.datetime` | `datetime.time`) –

        Time in or at which the job should run. This parameter will be interpreted depending on its type.

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

      - chat_id (`int`, optional) –

        Chat id of the chat associated with this job. If passed, the corresponding `chat_data` will be available in the callback.

        Added in version 20.0.

      - user_id (`int`, optional) –

        User id of the user associated with this job. If passed, the corresponding `user_data` will be available in the callback.

        Added in version 20.0.

      - data (`object`, optional) –

        Additional data needed for the callback function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

        Changed in version 20.0: Renamed the parameter `context` to `data`.

      - name (`str`, optional) – The name of the new job. Defaults to `callback.__name__`.

      - job_kwargs (`dict`, optional) – Arbitrary keyword arguments to pass to the `apscheduler.schedulers.base.BaseScheduler.add_job()`.

    Returns:

      The new `Job` instance that has been added to the job queue.

    Return type:

      `telegram.ext.Job`

  run_repeating(callback, interval, first=None, last=None, data=None, name=None, chat_id=None, user_id=None, job_kwargs=None)

    Creates a new `Job` instance that runs at specified intervals and adds it to the queue.

    Note

    For a note about DST, please see the documentation of APScheduler.

    Parameters:

      - callback (coroutine function) –

        The callback function that should be executed by the new job. Callback signature:

            async def callback(context: CallbackContext)

      - interval (`int` | `float` | `datetime.timedelta`) – The interval in which the job will run. If it is an `int` or a `float`, it will be interpreted as seconds.

      - first (`int` | `float` | `datetime.timedelta` | `datetime.datetime` | `datetime.time`, optional) –

        Time in or at which the job should run. This parameter will be interpreted depending on its type.

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

        Defaults to `interval`

        Note

        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)

        See also

        `telegram.ext.Job.run()`

      - last (`int` | `float` | `datetime.timedelta` | `datetime.datetime` | `datetime.time`, optional) –

        Latest possible time for the job to run. This parameter will be interpreted depending on its type. See `first` for details.

        If `last` is `datetime.datetime` or `datetime.time` type and `last.tzinfo` is `None`, the default timezone of the bot will be assumed, which is UTC unless `telegram.ext.Defaults.tzinfo` is used.

        Defaults to `None`.

      - data (`object`, optional) –

        Additional data needed for the callback function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

        Changed in version 20.0: Renamed the parameter `context` to `data`.

      - name (`str`, optional) – The name of the new job. Defaults to `callback.__name__`.

      - chat_id (`int`, optional) –

        Chat id of the chat associated with this job. If passed, the corresponding `chat_data` will be available in the callback.

        Added in version 20.0.

      - user_id (`int`, optional) –

        User id of the user associated with this job. If passed, the corresponding `user_data` will be available in the callback.

        Added in version 20.0.

      - job_kwargs (`dict`, optional) – Arbitrary keyword arguments to pass to the `apscheduler.schedulers.base.BaseScheduler.add_job()`.

    Returns:

      The new `Job` instance that has been added to the job queue.

    Return type:

      `telegram.ext.Job`

  property scheduler_configuration

    Provides configuration values that are used by `JobQueue` for `scheduler`.

    Tip

    Since calling `scheduler.configure()` deletes any previous setting, please make sure to pass these values to the method call in addition to your custom values:

        scheduler.configure(..., **job_queue.scheduler_configuration)

    Alternatively, you can also use methods like `add_jobstore()` to avoid using `configure()` altogether.

    Added in version 20.7.

    Returns:

      The configuration values as dictionary.

    Return type:

      dict[`str`, `object`]

  set_application(application)

    Set the application to be used by this JobQueue.

    Parameters:

      application (`telegram.ext.Application`) – The application.

  async start()

    Starts the `JobQueue`.

  async stop(wait=True)

    Shuts down the `JobQueue`.

    Parameters:

      wait (`bool`, optional) – Whether to wait until all currently running jobs have finished. Defaults to `True`.