Cron Expression Parser and Evaluator

2.7 · active · verified Thu Apr 09

cronsim is a Python library (current version 2.7) for parsing cron expressions and simulating their execution. It allows calculating the next scheduled run time based on a given start date. It receives low but steady maintenance, with updates for bug fixes and minor features.

Warnings

breaking Version 2.0.0 introduced a complete rewrite of the library in Python, moving away from its previous JavaScript-based implementation (node-cron). This means the API is entirely different for users migrating from versions prior to 2.0.0.
Fix: Review the `CHANGELOG.md` and `README.md` for specific migration steps. Essentially, it's a new library requiring a full re-implementation of cron logic.
gotcha cronsim requires Python 3.10 or newer. Attempting to install or run it on older Python versions will result in dependency resolution errors or runtime failures.
Fix: Ensure your project's Python environment is 3.10 or newer. Upgrade your Python interpreter if necessary.
gotcha The `next()` method calculates the *next* occurrence strictly *after* the `start_date` parameter. If `start_date` itself happens to be a valid cron execution time, it will not be returned; instead, the subsequent run time will be given.
Fix: If you need to include `start_date` as a potential run time, you might need to check `start_date` against the cron expression separately or adjust `start_date` slightly backwards (e.g., by 1 microsecond) before calling `next()`.

Install

pip install cronsim Install latest version

Imports

CronSim
```
from cronsim import CronSim
```

Quickstart

Initialize CronSim with a cron expression and use the `.next()` method to find the next scheduled run after a given datetime object.

from datetime import datetime
from cronsim import CronSim

# Daily at midnight
cron_expression = "0 0 * * *"
sim = CronSim(cron_expression)

# Get the next run after a specific date
start_date = datetime(2023, 1, 1, 10, 30, 0)
next_run = sim.next(start_date)
print(f"Cron expression: '{cron_expression}'")
print(f"Next run after {start_date}: {next_run}")

# Example with a more frequent schedule (every 15 minutes)
cron_expression_2 = "*/15 * * * *"
sim_2 = CronSim(cron_expression_2)
start_date_2 = datetime(2024, 7, 15, 14, 0, 0)
next_run_2 = sim_2.next(start_date_2)
print(f"\nCron expression: '{cron_expression_2}'")
print(f"Next run after {start_date_2}: {next_run_2}")

view raw JSON →