Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
Toggle table of contents sidebar

# 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

  Use In

  `telegram.ext.ApplicationBuilder.job_queue()`

  Available In

  - `telegram.ext.Application.job_queue`

  - `telegram.ext.CallbackContext.job_queue`

  See also

  Architecture Overview, Job Queue

  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 pending/scheduled jobs with the given name that are currently in the `JobQueue`.

    Returns:

      Tuple of all pending or 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()`.

    New in version 20.4.

    Parameters:

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

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

  jobs()

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

    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.

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

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

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

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

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

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

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

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

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

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

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