cron-validator

library1.0.8pypypi✓ verified 24d ago

cron-validator is a Python library providing tools for validating Unix cron expressions, matching specific datetimes against a cron pattern, and generating a sequence of datetimes that fulfill a given cron expression. It also includes a `CronScheduler` for simple task scheduling. Currently at version 1.0.8, the library receives regular, minor updates primarily for bug fixes and feature enhancements, such as extended cron rule support.

devops workflow

pip install cron-validator

github ↗package ↗

INSTALL

IMPORT

SIG · CRON-VALIDATOR

cron-validator

devopspythonv1.0.8

Install

1.8s avg

Import

62ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.8 · 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.064s · 21.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.060s · 22MB

20MB installed

● package 20MB

Code

Verified usage

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

CronValidator

✓ from cron_validator import CronValidator

CronScheduler

✓ from cron_validator import CronScheduler

str_to_datetime

✓ from cron_validator.util import str_to_datetime

Utility function for parsing datetime strings; standard `datetime` module or `dateutil` are alternatives.

This quickstart demonstrates how to validate cron expressions, check if a specific datetime matches a cron expression, and generate future execution times within a given range.

from datetime import datetime from cron_validator import CronValidator from cron_validator.util import str_to_datetime # 1. Validate a cron expression assert CronValidator.parse('* * * * *') is not None # Valid Unix cron assert CronValidator.parse('*/61 * * * *') is None # Invalid minute (max 59) # 2. Match a datetime with a cron expression dt_str = '2019-04-23 01:00' dt = str_to_datetime(dt_str) assert CronValidator.match_datetime('* * * * *', dt) is True assert CronValidator.match_datetime('0 * * * *', dt) is False # Does not match minute 0 # 3. Generate matching datetimes between two dates from_dt_str = '2026-04-11 10:00' to_dt_str = '2026-04-11 12:00' from_dt = str_to_datetime(from_dt_str) to_dt = str_to_datetime(to_dt_str) print(f"Next executions for '0 * * * *' between {from_dt_str} and {to_dt_str}:") for execution_dt in CronValidator.get_execution_time( '0 * * * *', from_dt=from_dt, to_dt=to_dt ): print(execution_dt) # Expected output for the example above: # 2026-04-11 11:00:00 # 2026-04-11 12:00:00

Debug

Known issues

gotchaThe library supports 'partially extended rules based on the Amazon EventBridge rule set' (from v1.0.6), which means its cron dialect might differ from strict Unix cron or Quartz cron standards. Always verify specific expressions against the library's implementation. For example, AWS EventBridge cron expressions do not support seconds.

fix

Consult the library's GitHub README for specific syntax support. Test cron expressions thoroughly if migrating from other cron systems.

affects: >=1.0.6

gotchaThe `CronScheduler` is provided for repetitive tasks, but its sample usage often involves a blocking `while True` loop. This design is not suitable for asynchronous applications or long-running processes without external event loop integration (e.g., `asyncio`, `APScheduler`).

fix

Integrate `CronScheduler.time_for_execution()` checks into an existing event loop or use a separate thread/process to prevent blocking your main application.

affects: All versions

deprecatedPrior to v1.0.7, the library did not support month names (e.g., `JAN`, `FEB`) or day of week names (e.g., `MON`, `TUE`) in cron expressions. Using such names in earlier versions would have resulted in validation failures.

fix

Upgrade to version 1.0.7 or later to use named values. For older versions, use numeric representations (e.g., `1-12` for months, `0-6` or `1-7` for days of week).

affects: <1.0.7

breakingIn versions prior to 1.0.1, the `get_execution_time` method might not have rounded execution datetimes to the minute level, potentially returning datetimes with non-zero seconds or microseconds.

fix

Upgrade to version 1.0.1 or later to ensure all generated execution datetimes are minute-aligned (seconds and microseconds set to 0). If using older versions, manually normalize the datetimes if minute-level precision is critical.

affects: <1.0.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cron_validator'

The 'cron-validator' library is not installed in the Python environment where the code is being executed, or the environment's Python path does not include the installation location.

fix

Install the library using pip: `pip install cron-validator`

ValueError: Invalid cron expression

While the `cron-validator` library's `parse()` method returns `None` for invalid expressions, this `ValueError` is a common error message generated by other cron validation tools or custom validation logic that wraps `cron-validator` when a cron string has incorrect syntax or invalid field values.

fix

Review the cron string for syntax errors, out-of-range values (e.g., day of month > 31, hour > 23), or incorrect number of fields. Use an online cron validator to help identify issues.

AttributeError: 'NoneType' object has no attribute '...'

The `CronValidator.parse()` method returns `None` when an invalid cron expression is provided. This `AttributeError` occurs when you attempt to call a method (e.g., `match_datetime`, `get_execution_time`) on the `None` object returned by `parse()` without first checking if the parsing was successful.

fix

Always check if `CronValidator.parse()` returned a valid object (not `None`) before attempting to use its methods. For example: `cron_expression_obj = CronValidator.parse(cron_string); if cron_expression_obj: # proceed with using cron_expression_obj`

Upgrade

Version history

1.0.8latest on PyPI · released Jun 19, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vcoder4c/cron-validator ↗

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