Cron Schedule Triggers

Common errors

• ValueError: Invalid cron string provided: '*,*,*,*,*', expecting 7 fields for Quartz Cron, received 5.

  cause Attempting to use a 5-field UNIX cron expression with the `QuartzCron` class, which expects a 7-field Quartz cron string.
  fix Convert the 5-field UNIX cron string to a 7-field Quartz cron string. Prepend a '0' for the seconds field and add a '?' for the day-of-week (or year if not used) to align with Quartz syntax. Example: `0 * * * * ? *` for 'every minute'.

• The `next_trigger()` method returns `None` or an empty list, even when the schedule seems valid.

  cause This often happens due to conflicting values in the 'day-of-month' and 'day-of-week' fields, or incorrect use of the `?` (no specific value) character. If both fields are specified (e.g., `*` for both), or both have specific numbers, the cron expression might not resolve to any valid dates.
  fix In Quartz cron, you must use `?` in *one* of the 'day-of-month' or 'day-of-week' fields if the other has a specific value. For example, to run on the 15th of every month, use `0 0 0 15 * ? *`. To run every Monday, use `0 0 0 ? * MON *`. If both are `*`, it acts as an OR, which might not be the desired behavior or can lead to unexpected results.

Warnings

• gotcha This library explicitly uses *Quartz Cron syntax*, which is a 7-field cron expression (seconds, minutes, hours, day-of-month, month, day-of-week, year) and supports unique special characters (like `L`, `W`, `#`). This differs significantly from the more common 5-field UNIX cron syntax. Misinterpreting the syntax is a frequent source of errors.
  Fix: Refer to Quartz Cron documentation for correct syntax. Always include the seconds field (position 1) and use `?` for 'no specific value' to resolve conflicts between day-of-month and day-of-week fields.
• gotcha This library is solely for *calculating* future trigger dates based on a cron expression. It does not provide any functionality for executing tasks or jobs. Users must integrate it with a separate task runner, job scheduler (e.g., `APScheduler`), or system `cron` daemon to actually perform scheduled operations.
  Fix: Understand that `cron-schedule-triggers` is a date calculation utility. Pair it with a separate execution mechanism if you need to run scheduled tasks.

Install

• pip install cron-schedule-triggers Install latest version

Imports

• QuartzCron

  from cstriggers.core.trigger import QuartzCron

Quickstart

Initializes a `QuartzCron` object with a cron string and start/end dates, then retrieves the next scheduled trigger date. Note the use of `datetime` objects for date parameters and the 7-field Quartz cron syntax.

from datetime import datetime
from cstriggers.core.trigger import QuartzCron

# Example: Every day, every hour, on the 0th minute and 0th second
# using Quartz Cron Syntax (seconds, minutes, hours, day-of-month, month, day-of-week, year)
# '?' means no specific value for that field to avoid conflicts (e.g., between day-of-month and day-of-week)
schedule_string = "0 0 * * * ? *"

# Define start and (optional) end dates as datetime objects
start_date = datetime(2023, 1, 1, 0, 0, 0)
end_date = datetime(2024, 1, 1, 0, 0, 0) # Inclusive end

# Initialize the cron object
cron_obj = QuartzCron(schedule_string=schedule_string, start_date=start_date, end_date=end_date)

# Get the next trigger date
next_trigger_date = cron_obj.next_trigger()
print(f"Next trigger: {next_trigger_date.isoformat()}")

# Get multiple trigger dates
print("\nUpcoming 3 triggers:")
for _ in range(3):
    next_trigger = cron_obj.next_trigger()
    if next_trigger:
        print(next_trigger.isoformat())
    else:
        print("No more triggers within the specified range.")
        break