Description

Currently, Docket excels at scheduling future work via timedelta and self-perpetuating tasks using the Perpetual dependency. However, I don't know of a native way to express "Wall Clock" schedules, such as "Every Monday at 9:00 AM" or "At the start of every hour."

Proposed Solution

I'd love to see a first-class Cron dependency that can be used similarly to Perpetual. This would allow Docket to handle the "wait until" logic internally.

from docket import Docket, Cron

docket = Docket()

# Option A: Standard Cron string
async def weekly_report(cron: Cron = Cron("0 9 * * 1")):
    print("Generating Monday morning report...")

# Option B: Human-readable helper (similar to the 'schedule' library)
async def daily_cleanup(cron: Cron = Cron.daily(at="03:00")):
    print("Cleaning up database...")

Behind the scenes, the Cron dependency could:

• Use a library like croniter or python-crontab to calculate the next datetime.
• Automatically reschedule the task using the existing docket.add(when=next_run) logic once the current task completes.

Why this helps

• It eliminates the need for an external orchestrator like apscheduler or celery-beat.
• Keeps tasks "on track": Unlike a simple timedelta(hours=24), a Cron dependency ensures that if a task starts late, the next one still fires at the intended wall-clock time.
• Protects from interval drift. If a daily task takes 5 minutes to run, the "next" run is actually 24 hours and 5 minutes from the previous start. Over a month, the "Daily at 9:00 AM" task might end up running at 11:30 AM.

Would you be open to adding a cron-parsing dependency to the core, or perhaps an optional docket[cron] extra?