croniter-rs 0.1.0

High-performance Rust implementation of Python croniter

croniter-rs

A high-performance Rust implementation of Python's croniter library, providing blazing-fast cron expression parsing and iteration.

Overview

croniter-rs is a drop-in replacement for the popular Python croniter library, written in Rust using PyO3 for seamless Python integration. It provides the same API while delivering significant performance improvements for cron schedule calculations.

Perfect for applications that need to:

• Calculate thousands of cron schedule occurrences
• Validate cron expressions at scale
• Match datetime objects against cron patterns efficiently
• Iterate through cron schedules with minimal overhead

Features

• Drop-in Replacement: Compatible API with Python's croniter library
• High Performance: 15-55x faster than pure Python implementation
• Full Cron Syntax Support:
  • Standard 5-field format: minute hour day month weekday
  • Extended 6-field format with seconds: second minute hour day month weekday
• Advanced Syntax:
  • Last day of month: L
  • Nth weekday of month: # (e.g., MON#1 for first Monday)
  • Ranges: 1-5, MON-FRI
  • Steps: */5, 1-10/2
  • Lists: 1,2,3, MON,WED,FRI
  • Month and weekday names: JAN, FEB, MON, TUE
  • Hash expressions: H, H(0-30) (Jenkins-style)
• Flexible Return Types: Return datetime objects or Unix timestamps
• Bidirectional Iteration: Get next or previous occurrences
• Pattern Matching: Check if a datetime matches a cron expression
• Validation: Validate cron expressions before use

Installation

pip install croniter-rs

Requirements:

• Python 3.8 or higher
• No additional dependencies required

Quick Start

Basic Usage

from croniter_rs import croniter
from datetime import datetime

# Create a cron iterator
base = datetime(2024, 1, 1, 0, 0)
cron = croniter('*/5 * * * *', base)  # Every 5 minutes

# Get next occurrence
next_time = cron.get_next(datetime)
print(next_time)  # 2024-01-01 00:05:00

# Get next occurrence as timestamp
next_timestamp = cron.get_next(float)
print(next_timestamp)  # 1704067500.0

Iterating Through Occurrences

from croniter_rs import croniter
from datetime import datetime

# Create iterator
cron = croniter('0 0 * * *', datetime(2024, 1, 1))  # Daily at midnight

# Get next 5 occurrences
for i in range(5):
    print(cron.get_next(datetime))

# Or use Python iterator protocol
cron = croniter('0 */6 * * *', datetime(2024, 1, 1))  # Every 6 hours
for time in cron:
    print(time)
    if time > datetime(2024, 1, 7):
        break

Getting Previous Occurrences

from croniter_rs import croniter
from datetime import datetime

cron = croniter('0 0 * * *', datetime(2024, 1, 15))

# Get previous occurrence
prev_time = cron.get_prev(datetime)
print(prev_time)  # 2024-01-14 00:00:00

# Get multiple previous occurrences
prev_times = cron.get_prev_n(5, datetime)
print(prev_times)

Validating Cron Expressions

from croniter_rs import croniter

# Check if expression is valid
if croniter.is_valid('0 0 * * *'):
    print("Valid cron expression")

if not croniter.is_valid('invalid expression'):
    print("Invalid cron expression")

Matching Datetime Against Pattern

from croniter_rs import croniter
from datetime import datetime

# Check if a datetime matches a cron pattern
dt = datetime(2024, 1, 1, 12, 0)

if croniter.match('0 12 * * *', dt):
    print("Datetime matches the pattern")

if not croniter.match('0 0 * * *', dt):
    print("Datetime does not match")

API Compatibility

croniter-rs provides a drop-in replacement API for Python croniter. The following table shows the compatibility status:

Fully Compatible Methods

Method	Status	Notes
croniter(expr, start_time, ...)	✅	Constructor with all parameters
get_next(ret_type)	✅	Get next occurrence
get_prev(ret_type)	✅	Get previous occurrence
get_current(ret_type)	✅	Get current time
set_current(time)	✅	Set current time
next(ret_type)	✅	Alias for get_next()
all_next(ret_type)	✅	Returns iterator for forward iteration
all_prev(ret_type)	✅	Returns iterator for backward iteration
iter(ret_type)	✅	Returns iterator
is_valid(expr)	✅	Class method to validate expression
match(expr, dt)	✅	Class method to check if datetime matches
expand(expr)	✅	Class method to expand expression
match_range(expr, start, end)	✅	Check if match exists in time range
expanded	✅	Property returning expanded field values
__iter__ / __next__	✅	Python iterator protocol

Additional Methods (croniter-rs only)

Method	Description
get_next_n(n, ret_type)	Get next n occurrences as a list
get_prev_n(n, ret_type)	Get previous n occurrences as a list

Migration Guide

For most use cases, migration is a simple import change:

# Before
from croniter import croniter

# After
from croniter_rs import croniter

No other code changes are required for standard usage patterns.

Benchmarks

Performance comparison between croniter-rs and pure Python croniter:

Operation	croniter (Python)	croniter-rs (Rust)	Speedup
Constructor	83.79 μs	6.09 μs	13.8x
get_next()	24.62 μs	0.52 μs	47.0x
get_prev()	24.37 μs	0.49 μs	49.9x
is_valid()	79.77 μs	5.27 μs	15.1x
match()	114.97 μs	5.85 μs	19.7x
Complex expression	28.38 μs	0.56 μs	50.7x
Batch 1000 iterations	24.93 ms	0.45 ms	55.3x

Benchmarks run on: Linux 6.8.0, Python 3.10, 10000 iterations per operation

The performance advantage is especially significant when:

• Calculating many occurrences in a loop (up to 55x faster)
• Iterating through schedules with get_next()/get_prev() (47-50x faster)
• Validating large numbers of cron expressions (15x faster)
• Performing pattern matching on high-frequency data (20x faster)

Behavior Differences from Python croniter

croniter-rs adopts a semantic equivalence principle for day_or logic, which leads to more consistent and predictable behavior. This section documents the differences and explains the design rationale.

Background: The day_or Logic

According to POSIX cron specification:

• If both day-of-month and day-of-week are specified (not *), the job runs when either condition is met (OR logic)
• If one of them is *, only the other field is checked

The key question is: Should ranges that cover all values (like 0-6 for weekday or 1-31 for day) be treated as equivalent to *?

Interpretation	0-6 / 1-31 treated as	Behavior
Strict	Explicit range (not *)	Triggers day_or logic
Semantic	Equivalent to *	Does NOT trigger day_or logic

croniter-rs uses semantic interpretation consistently, while Python croniter is inconsistent (uses strict for weekday, semantic for day).

Difference 1: Weekday Full Range (0-6, sun-sat)

When weekday covers all days (0-6, sun-sat), croniter-rs treats it as equivalent to *.

from datetime import datetime

# Expression: Run at midnight on the 15th of each month
# weekday=0-6 covers all days, semantically equivalent to *

expr1 = '0 0 15 * *'      # weekday = * (wildcard)
expr2 = '0 0 15 * 0-6'    # weekday = 0-6 (all days)

start = datetime(2024, 1, 1)  # January 1st is Monday

# Python croniter results:
#   expr1 → 2024-01-15 (Mon) ✓ Correct
#   expr2 → 2024-01-01 (Mon) ✗ Wrong - day_or triggered incorrectly

# croniter-rs results:
#   expr1 → 2024-01-15 (Mon) ✓ Correct
#   expr2 → 2024-01-15 (Mon) ✓ Correct - 0-6 treated as *

Difference 2: Day Full Range (1-31)

When day-of-month covers all days (1-31), croniter-rs treats it as equivalent to *.

from datetime import datetime

# Expression: Run at midnight on Sun/Tue/Thu in April
# day=1-31 covers all days, semantically equivalent to *

expr1 = '0 0 * 4 0,2,4'     # day = * (wildcard)
expr2 = '0 0 1-31 4 0,2,4'  # day = 1-31 (all days)

start = datetime(2024, 1, 1)

# Python croniter results:
#   expr1 → 2024-04-02 (Tue) ✓ Correct
#   expr2 → 2024-04-01 (Mon) ✗ Wrong - ignores weekday constraint

# croniter-rs results:
#   expr1 → 2024-04-02 (Tue) ✓ Correct
#   expr2 → 2024-04-02 (Tue) ✓ Correct - 1-31 treated as *

Compatibility Note

These differences affect approximately 0.3-0.5% of randomly generated complex cron expressions. Common cron patterns (like 0 0 * * *, */5 * * * *, 0 9 * * 1-5) are 100% compatible.

Known Limitations

1. 7-field format (year field): Not yet supported.

2. Word aliases: Special aliases like @hourly, @daily, @weekly, @monthly, @yearly, and @reboot are not yet implemented.

3. Timezone support: Currently uses naive datetime objects.

Exception Types

croniter-rs provides the same exception types as the original croniter:

• CroniterBadCronError: Invalid cron expression syntax
• CroniterBadDateError: Invalid date/time value
• CroniterNotAlphaError: Invalid alphabetic value in expression
• CroniterUnsupportedSyntaxError: Unsupported cron syntax feature

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Original croniter library by kiorky
• Built with PyO3 for Rust-Python interoperability