API reference: Job

class schedium.types.cancel_job.CancelJob(reason=None)

Bases: object

Return value that cancels (removes) the current job.

If a job’s callable returns an instance of CancelJob, schedium.scheduler.Scheduler.run_pending() will remove that job from the scheduler.

Attributes:

reasonstr | None, default None

Optional human-readable reason for cancellation.

Parameters:

reason (str | None)

reason: str | None

class schedium.job.Job(func, trigger, name=None)

Bases: object

A scheduled unit of work.

Parameters:

funcCallable[[], object]

A zero-argument callable. The return value is returned by run() and by schedium.scheduler.Scheduler.run_pending(). If you need to pass arguments, wrap them in a closure or functools.partial.

triggerBaseTrigger

The trigger that decides when this job is due.

namestr, default None

Optional human-readable label used in repr(job).

Parameters:

• func (Callable[[], object])

• trigger (BaseTrigger)

• name (str | None)

Notes

Deduplication

A job runs at most once per trigger event token.

Internally, schedium.utils.evaluate.evaluate() turns a trigger match into a schedium.triggers.base.TriggerEvent. The event’s token typically represents a time bucket (minute/hour/day, etc.). If the scheduler is called multiple times within the same bucket, the job is considered not due after the first run.

State

Jobs are stateful: last_event is updated on successful run(). If you want the same callable to run under multiple independent schedules, create multiple Job instances.

Threading

Jobs do not run in separate threads/processes by default. The scheduler runs them inline.

is_due(now)

Return True if the job should run at now.

A job is due when:

1. its trigger matches at now and yields an event token, and

2. that token is different from the last token the job already ran for.

This method does not mutate state.

Parameters:

nowdatetime

Timestamp used to evaluate the trigger.

Returns:

bool

True if the job is due at now.

Parameters:

now (datetime)

Return type:

bool

run(now)

Run the job if due, update last_event, and return the result.

Parameters:

nowdatetime

Timestamp used to evaluate the trigger.

Returns:

object

The callable’s return value.

Raises:

RuntimeError

If called when the job is not due, or if called again for the same trigger token (double-run protection).

Parameters:

now (datetime)

Return type:

object

run_func()

Run the job’s callable without checking triggers or updating state.

Particularly useful to override in subclasses that want to customize the run behavior while keeping the same trigger-based scheduling logic.

Returns:

object

The callable’s return value.

Return type:

object

datetime_of_next_run(after=None, *, max_iterations=100000)

Return the next run datetime for this job.

This is derived from the trigger’s next validity window.

Parameters:

afterdatetime, optional

Lower bound (inclusive) for the computed next run time. If omitted, uses the current system time.

max_iterationsint, default 100_000

Safety cap used by some triggers/combinators that scan forward.

Returns:

datetime | None

The earliest datetime at which this job is due, or None if the trigger tree cannot produce a next window.

Parameters:

• after (datetime | None)

• max_iterations (int)

Return type:

datetime | None