cron-converter

library2.0.1pypypi✓ verified 25d ago

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.

workflow

pip install cron-converter

github ↗package ↗

INSTALL

IMPORT

SIG · CRON-CONVERTER

cron-converter

workflowpythonv2.0.1

Install

1.7s avg

Import

38ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.040s · 18.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.036s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

Cron

✓ from cron_converter import Cron

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()}")

cron-converter --version

Debug

Known issues

gotchaThe `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.

affects: 1.3.0 and later (since Seeker object implements Iterator protocol)

gotchaFor 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`.

affects: All versions

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.

affects: Users of `croniter`

gotchaConstructor 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})`.

affects: All versions

Errors

Common errors & fixes

ValueError: Invalid cron expression

The cron string provided to the `cron-converter` library does not conform to a valid cron expression format.

fix

Review and correct the cron expression to ensure it follows the standard 5-field (or 6-field with seconds) cron syntax, e.g., '*/5 * * * *' for every five minutes.

ModuleNotFoundError: No module named 'cron_converter'

This typically occurs when a Python script using `cron-converter` is executed as a system cron job, and the cron environment does not have access to the Python interpreter or virtual environment where `cron-converter` is installed.

fix

Specify the full path to the Python interpreter (e.g., from your virtual environment) in the crontab entry, or ensure that `cron-converter` is installed in the system's default Python environment that cron uses.

Program hangs or consumes excessive resources when iterating cron schedule

The `Cron().schedule()` method returns an infinite iterator, and without an explicit limit or break condition, the program will attempt to generate an endless sequence of datetimes.

fix

Implement a mechanism to limit the iteration, such as using `itertools.islice()` to get a fixed number of future occurrences, or add a `break` statement based on a specific condition (e.g., a target end date).

Upgrade

Version history

2.0.1latest on PyPI · released Aug 17, 2026

Audit

Dependencies

python-dateutilrequiredUsed for timezone-aware datetime operations within the scheduler.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Sonic0/cron-converter ↗

packagehttps://pypi.org/project/cron-converter/ ↗