Registry / workflow / cronsim

cronsim

JSON →
library2.7pypypi✓ verified 26d ago

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.

pip install cronsim
INSTALL
IMPORT
SIG · CRONSIM
C
cronsim
workflowpythonv2.7
Install
1.5s avg
Import
18ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.018s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.5s · import 0.018s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CronSim
from cronsim import CronSim

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}")
Debug
Known issues
breakingVersion 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.
affects: < 2.0.0
gotchacronsim 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.
affects: All versions >= 2.0
gotchaThe `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()`.
affects: All versions
Errors
Common errors & fixes
cronsim.cronsim.CronSimError: Bad minute
This error occurs when the cron expression provided to `cronsim` contains an invalid value or incorrect syntax in one of its fields, such as the minute, hour, or day of the month.
fix
Review and correct the cron expression to ensure all fields adhere to the standard cron syntax and allowed value ranges (e.g., minutes 0-59, hours 0-23). For example, '123 * * * *' would cause a 'Bad minute' error because 123 is an invalid minute value.
StopIteration
The `cronsim` iterator raises `StopIteration` when it cannot find any more matching datetimes within its internal search limit (e.g., 50 years by default) or the logical end of its sequence, meaning no further scheduled times exist for the given cron expression and start date.
fix
Catch the `StopIteration` exception to gracefully handle the end of the iteration. Alternatively, adjust the cron expression or the start date if you expect more matching datetimes, or consider that the schedule simply has no more occurrences within the simulated timeframe.
ModuleNotFoundError: No module named 'cronsim'
This error indicates that the Python interpreter executing the script cannot locate the `cronsim` library. This is frequently encountered when the library is installed in a different Python environment (e.g., a virtual environment) than the one being used by the script, or when a script is run by a cron job that has a different `PATH` or `PYTHONPATH` environment than the user's shell.
fix
Ensure `cronsim` is installed in the correct Python environment using `pip install cronsim`. If running a script via a cron job, specify the absolute path to the Python interpreter that has `cronsim` installed (e.g., `/usr/bin/python3 /path/to/your_script.py`) or activate the virtual environment within the cron job.
Upgrade
Version history
2.7latest on PyPI · released Oct 21, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
cronsim — pip install cronsim · libregistry