Cron-converter

1.3.1 · active · verified Sat Apr 11

Cron-converter is a Python library that provides a cron string parser and scheduler. It allows parsing cron expressions from strings or lists and iterating over datetime objects in a cron-like format. It is a transposition of the JavaScript cron-converter library and is currently at version 1.3.1, actively maintained with regular releases.

Warnings

gotcha The `schedule()` method returns an infinite iterator. To avoid unbounded loops, always use limiting mechanisms like `itertools.islice()` or implement explicit break conditions.
Fix: Wrap the `schedule()` call with `itertools.islice(cron_instance.schedule(start_date), num_iterations)` or add manual break logic within your loop.
gotcha For correct handling of Daylight Saving Time (DST) and timezone conversions, initialize your `Cron` instance's `schedule` method with a timezone-aware `datetime` object or specify a `timezone_str`. By default, `schedule` starts with a UTC datetime.
Fix: When calling `cron_instance.schedule()`, pass a `datetime` object with `tzinfo` set, e.g., `datetime.now(pytz.timezone('America/New_York'))` or `datetime.now(dateutil.tz.gettz('Asia/Tokyo'))` if using `python-dateutil`.
deprecated `cron-converter` has been recommended as a replacement for the `croniter` library, which is set to be decommissioned. Users migrating from `croniter` should be aware of API differences.
Fix: Update imports and refactor code to use `cron-converter`'s `Cron` class and `schedule()` method. Refer to `cron-converter` documentation for specific API changes.
gotcha Constructor options like `output_weekday_names`, `output_month_names`, and `output_hashes` are available to modify the output format of the cron string. These are `false` by default.
Fix: Pass a dictionary of options to the `Cron` constructor: `cron_instance = Cron('...', {'output_weekday_names': True})`.

Install

pip install cron-converter Install stable release

Imports

Cron
```
from cron_converter import Cron
```

Quickstart

This quickstart demonstrates how to initialize a `Cron` object with a cron string, retrieve its string and list representations, and iterate over upcoming scheduled times using the `schedule` method. It also shows how to use constructor options for named output and highlights the importance of using `itertools.islice` or similar mechanisms when iterating over the (infinite) schedule.

from cron_converter import Cron
from datetime import datetime
from itertools import islice
import dateutil.tz # Dependency for timezone-aware operations

# Example 1: Basic cron parsing and iteration (UTC)
cron_expression_str = '*/10 9-17 * * MON-FRI'
cron_instance = Cron(cron_expression_str)

print(f"Cron expression: {cron_instance.to_string()}")
print(f"Cron list representation: {cron_instance.to_list()}")

# Get a schedule iterator, starting from a specific datetime
start_time = datetime(2026, 4, 14, 8, 0, 0, tzinfo=dateutil.tz.UTC)
# The schedule iterator is infinite, use islice or explicit breaks
schedule = cron_instance.schedule(start_time)

print(f"Next 5 scheduled times after {start_time}:")
for i, next_run in enumerate(islice(schedule, 5)):
    print(f"  {i+1}: {next_run}")

# Example 2: With constructor options (outputting names)
cron_with_names = Cron('*/5 9-17 * 1-3 MON-FRI', {
    'output_weekday_names': True,
    'output_month_names': True
})
print(f"Cron with names: {cron_with_names.to_string()}")

view raw JSON →