cronlex

A small, dependency-free cron expression parser and explainer. Translate cron syntax into plain English, validate each field, and preview the next N scheduled runs.

Cron expressions are concise but easy to misread. cronlex makes them legible at a glance and helps you catch mistakes before they end up in production crontabs.

Features

• Parse standard 5-field cron expressions (minute hour day-of-month month day-of-week)
• Translate any valid expression into a human-readable description
• Validate every field with precise error messages (range, step, list, name)
• Preview the next N execution times from any starting point
• Support common aliases: @yearly, @annually, @monthly, @weekly, @daily, @hourly
• Zero runtime dependencies, pure Python 3.8+

Install

Clone and use directly — no install required:

git clone https://github.com/Jerrytriple8/cronlex.git
cd cronlex
python -m cronlex "*/15 9-17 * * 1-5"

Or install locally with pip:

pip install .

Usage

CLI

$ python -m cronlex "*/15 9-17 * * 1-5"
Expression: */15 9-17 * * 1-5
Meaning:    Every 15 minutes, between 09:00 and 17:00, Monday through Friday

Next 5 runs:
  2026-05-22 09:00:00
  2026-05-22 09:15:00
  2026-05-22 09:30:00
  2026-05-22 09:45:00
  2026-05-22 10:00:00

Show only the description:

python -m cronlex --describe "0 0 1 */3 *"
# At 00:00 on day-of-month 1, every 3rd month

Show the next 10 runs from a custom start time:

python -m cronlex --next 10 --from "2026-06-01 00:00" "30 2 * * 0"

Validate without describing:

python -m cronlex --validate "60 * * * *"
# Error: minute field value 60 out of range 0-59

Library

from cronlex import CronExpression

cron = CronExpression("*/15 9-17 * * 1-5")

print(cron.describe())
# 'Every 15 minutes, between 09:00 and 17:00, Monday through Friday'

from datetime import datetime
start = datetime(2026, 5, 22, 8, 30)

for run in cron.next_runs(start, count=3):
    print(run.isoformat())
# 2026-05-22T09:00:00
# 2026-05-22T09:15:00
# 2026-05-22T09:30:00

Cron syntax reference

 ┌───────────── minute        (0 - 59)
 │ ┌───────────── hour        (0 - 23)
 │ │ ┌───────────── day of month (1 - 31)
 │ │ │ ┌───────────── month   (1 - 12 or JAN-DEC)
 │ │ │ │ ┌───────────── day of week (0 - 6 or SUN-SAT, 0 = Sunday)
 │ │ │ │ │
 * * * * *

Supported per-field operators:

Operator	Meaning	Example
*	every value	* * * * *
,	list of values	0,15,30,45 * * * *
-	range	9-17 * * * *
/	step	*/5 * * * *
names	month and weekday names	0 0 * JAN MON

Aliases

Alias	Equivalent
@yearly	0 0 1 1 *
@annually	0 0 1 1 *
@monthly	0 0 1 * *
@weekly	0 0 * * 0
@daily	0 0 * * *
@hourly	0 * * * *

Tests

python -m unittest discover -v

License

MIT