cron-converter

cron-converter parses standard 5-field cron expressions into structured representations and back, and provides a datetime-aware scheduler for walking forward or backward through a cron schedule’s execution times. It is a Python port of the JavaScript cron-converter library, adapted to Python’s datetime and dateutil ecosystem.

Beyond string parsing, it exposes a Seeker iterator that implements Python’s standard iterator protocol, so schedules can be consumed with next(), itertools.islice(), or a for loop, while still supporting timezone-aware start dates, DST handling via dateutil, and validation of arbitrary datetime objects against a cron rule.

What You Get

• Cron string <-> list parsing via from_string/to_string and from_list/to_list
• A Seeker iterator for schedule.next()/prev()/reset(), plus native Python iterator protocol support
• Timezone-aware and DST-safe scheduling via dateutil.tz
• Datetime validation against a cron rule via .validate() or the in operator
• Comparable Cron/Part objects (lt, eq) for comparing schedule frequency
• Human-readable output options: weekday/month names and Jenkins-style H hash notation

Common Use Cases

• Validating a stored cron string before saving it to a job scheduler config
• Computing the next N run times for a scheduled task in a dashboard UI
• Converting user-entered cron expressions into a normalized display string
• Checking whether a given timestamp falls within a cron schedule for audit/backfill logic
• Building a custom job scheduler that needs timezone-aware next-run calculations

Under The Hood

Architecture The library is organized around three collaborating classes under cron_converter/: Cron (cron.py) owns parsing and holds five Part objects (one per minute/hour/day/month/weekday field, defined via the unit metadata in sub_modules/units.py); Part (sub_modules/part.py) validates and normalizes a single field’s values, ranges, and step syntax into a sorted integer list, and renders it back to cron syntax; Seeker (sub_modules/seeker.py) walks a datetime forward or backward through month/day/hour/minute shifts until it lands on a moment all five Parts accept, implementing Python’s Iterator[datetime] protocol so it composes with next(), for-loops, and itertools.islice(). Cron.schedule() is the sole entry point into a Seeker, and Cron/Part both implement total_ordering-based comparisons so entire schedules can be ranked by execution frequency. The core abstraction that would break the most if changed is Part’s internal sorted-list-of-ints representation, since Seeker, to_string(), and validate() all depend on it directly.