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

# Job

class telegram.ext.Job(callback, data=None, name=None, chat_id=None, user_id=None)

  Bases: `typing.Generic`

  This class is a convenience wrapper for the jobs held in a `telegram.ext.JobQueue`. With the current backend APScheduler, `job` holds a `apscheduler.job.Job` instance.

  Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their `id` is equal.

  This class is a `Generic` class and accepts one type variable that specifies the type of the argument `context` of `callback`.

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

  Note

  All attributes and instance methods of `job` are also directly available as attributes/methods of the corresponding `telegram.ext.Job` object.

  Warning

  This class should not be instantiated manually. Use the methods of `telegram.ext.JobQueue` to schedule jobs.

  Available In

  `telegram.ext.CallbackContext.job`

  See also

  Job Queue

  Changed in version 20.0:

  - Removed argument and attribute `job_queue`.

  - Renamed `Job.context` to `Job.data`.

  - Removed argument `job`

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

  Parameters:

    - callback (coroutine function) –

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

          async def callback(context: CallbackContext)

    - data (`object`, optional) – Additional data needed for the `callback` function. Can be accessed through `Job.data` in the callback. Defaults to `None`.

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

    - chat_id (`int`, optional) –

      Chat id of the chat that this job is associated with.

      New in version 20.0.

    - user_id (`int`, optional) –

      User id of the user that this job is associated with.

      New in version 20.0.

  callback

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

    Type:

      coroutine function

  data

    Optional. Additional data needed for the `callback` function.

    Type:

      `object`

  name

    Optional. The name of the new job.

    Type:

      `str`

  chat_id

    Optional. Chat id of the chat that this job is associated with.

    New in version 20.0.

    Type:

      `int`

  user_id

    Optional. User id of the user that this job is associated with.

    New in version 20.0.

    Type:

      `int`

  __eq__(other)

    Defines equality condition for the `telegram.ext.Job` object. Two objects of this class are considered to be equal if their `id` are equal.

    Returns:

      `True` if both objects have `id` parameters identical. `False` otherwise.

  __getattr__(item)

    Overrides `object.__getattr__()` to get specific attribute of the `telegram.ext.Job` object or of its attribute `apscheduler.job.Job`, if exists.

    Parameters:

      item (`str`) – The name of the attribute.

    Returns:

      object: The value of the attribute.

    Raises:

      AttributeError – If the attribute does not exist in both `telegram.ext.Job` and `apscheduler.job.Job` objects.

  __hash__()

    Builds a hash value for this object such that the hash of two objects is equal if and only if the objects are equal in terms of `__eq__()`.

    Returns:

      The hash value of the object.

    Return type:

      `int`

  __repr__()

    Give a string representation of the job in the form `Job[id=..., name=..., callback=..., trigger=...]`.

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

    Returns:

      `str`

  property enabled

    Whether this job is enabled.

    Type:

      `bool`

  classmethod from_aps_job(aps_job)

    Provides the `telegram.ext.Job` that is associated with the given APScheduler job.

    Tip

    This method can be useful when using advanced APScheduler features along with `telegram.ext.JobQueue`.

    New in version 20.4.

    Parameters:

      aps_job (`apscheduler.job.Job`) – The APScheduler job

    Returns:

      `telegram.ext.Job`

  property job

    The APS Job this job is a wrapper for.

    Changed in version 20.0: This property is now read-only.

    Type:

      `apscheduler.job.Job`

  property next_t

    Datetime for the next job execution. Datetime is localized according to `datetime.datetime.tzinfo`. If job is removed or already ran it equals to `None`.

    Warning

    This attribute is only available, if the `telegram.ext.JobQueue` this job belongs to is already started. Otherwise APScheduler raises an `AttributeError`.

    Type:

      `datetime.datetime`

  property removed

    Whether this job is due to be removed.

    Type:

      `bool`

  async run(application)

    Executes the callback function independently of the jobs schedule. Also calls `telegram.ext.Application.update_persistence()`.

    Changed in version 20.0: Calls `telegram.ext.Application.update_persistence()`.

    Parameters:

      application (`telegram.ext.Application`) – The application this job is associated with.

  schedule_removal()

    Schedules this job for removal from the `JobQueue`. It will be removed without executing its callback function again.