0
# Croniter
1

2
Croniter provides iteration for datetime objects with a cron-like format. It enables developers to calculate next and previous execution times based on cron expressions, supports advanced cron features including second-level precision, year fields, timezone-aware calculations, and Jenkins-style hashed expressions. The library offers comprehensive cron validation, range matching, and supports various cron extensions like @yearly, @monthly shortcuts.
3

4
## Package Information
5

6
- **Package Name**: croniter
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install croniter`
10

11
## Core Imports
12

13
```python
14
from croniter import croniter
15
```
16

17
For range operations:
18

19
```python
20
from croniter import croniter_range
21
```
22

23
For validation and matching:
24

25
```python
26
from croniter import croniter
27
```
28

29
Complete import with exceptions and constants:
30

31
```python
32
from croniter import (
33
    croniter,
34
    croniter_range,
35
    datetime_to_timestamp,
36
    # Field constants
37
    MINUTE_FIELD,
38
    HOUR_FIELD,
39
    DAY_FIELD,
40
    MONTH_FIELD,
41
    SECOND_FIELD,
42
    YEAR_FIELD,
43
    OVERFLOW32B_MODE,
44
    UTC_DT,
45
    # Exception classes
46
    CroniterError,
47
    CroniterBadCronError,
48
    CroniterBadDateError,
49
    CroniterBadTypeRangeError,
50
    CroniterNotAlphaError,
51
    CroniterUnsupportedSyntaxError
52
)
53
```
54

55
## Basic Usage
56

57
```python
58
from croniter import croniter
59
from datetime import datetime
60

61
# Create a croniter instance for every 5 minutes
62
base = datetime(2010, 1, 25, 4, 46)
63
iter = croniter('*/5 * * * *', base)
64

65
# Get next execution times
66
print(iter.get_next(datetime))   # 2010-01-25 04:50:00
67
print(iter.get_next(datetime))   # 2010-01-25 04:55:00
68
print(iter.get_next(datetime))   # 2010-01-25 05:00:00
69

70
# Work with more complex expressions
71
iter = croniter('2 4 * * mon,fri', base)  # 04:02 on Monday and Friday
72
print(iter.get_next(datetime))   # 2010-01-26 04:02:00
73
print(iter.get_next(datetime))   # 2010-01-30 04:02:00
74
```
75

76
## Architecture
77

78
Croniter is built around the core `croniter` class which parses cron expressions and provides iteration capabilities. The library supports:
79

80
- **Standard cron formats**: 5-field Unix format (minute hour day month dayofweek)
81
- **Extended formats**: 6-field (with seconds) and 7-field (with year) support
82
- **Advanced features**: Hashed expressions (Jenkins-style "H"), random expressions ("R")
83
- **Timezone awareness**: Full DST and timezone support
84
- **Performance optimization**: Configurable limits for sparse expressions
85

86
Key components include:
87
- **croniter class**: Main iterator for datetime progression
88
- **croniter_range function**: Range-based iteration like Python's range()
89
- **Validation system**: Expression validation and datetime matching
90
- **Exception hierarchy**: Comprehensive error handling for various failure modes
91

92
## Capabilities
93

94
### Core Iteration
95

96
Main croniter class providing datetime iteration based on cron expressions, with support for both forward and backward iteration, timezone handling, and various cron formats.
97

98
```python { .api }
99
class croniter:
100
    def __init__(
101
        self,
102
        expr_format: str,
103
        start_time=None,
104
        ret_type=float,
105
        day_or=True,
106
        max_years_between_matches=None,
107
        is_prev=False,
108
        hash_id=None,
109
        implement_cron_bug=False,
110
        second_at_beginning=None,
111
        expand_from_start_time=False,
112
    ): ...
113
    
114
    def get_next(self, ret_type=None, start_time=None, update_current=True): ...
115
    def get_prev(self, ret_type=None, start_time=None, update_current=True): ...
116
```
117

118
[Core Iteration](./core-iteration.md)
119

120
### Range Operations
121

122
Range-based iteration functionality similar to Python's built-in range() function, but for datetime objects using cron expressions as the "step" parameter.
123

124
```python { .api }
125
def croniter_range(
126
    start,
127
    stop,
128
    expr_format: str,
129
    ret_type=None,
130
    day_or=True,
131
    exclude_ends=False,
132
    _croniter=None,
133
    second_at_beginning=False,
134
    expand_from_start_time=False,
135
): ...
136
```
137

138
[Range Operations](./range-operations.md)
139

140
### Validation and Matching
141

142
Comprehensive validation of cron expressions and testing whether specific datetime objects match cron patterns, including range-based matching.
143

144
```python { .api }
145
@classmethod
146
def is_valid(
147
    cls,
148
    expression: str,
149
    hash_id=None,
150
    encoding="UTF-8",
151
    second_at_beginning=False,
152
) -> bool: ...
153

154
@classmethod
155
def match(cls, cron_expression: str, testdate, day_or=True, second_at_beginning=False) -> bool: ...
156

157
@classmethod
158
def match_range(
159
    cls,
160
    cron_expression: str,
161
    from_datetime,
162
    to_datetime,
163
    day_or=True,
164
    second_at_beginning=False,
165
) -> bool: ...
166
```
167

168
[Validation and Matching](./validation-matching.md)
169

170
### Advanced Features
171

172
Advanced croniter features including Jenkins-style hashed expressions, random expressions, custom start time expansion, and specialized cron syntax support.
173

174
```python { .api }
175
# Hashed expressions
176
iter = croniter("H H * * *", hash_id="unique-job-id")
177

178
# Random expressions  
179
iter = croniter("R R * * *")
180

181
# Custom expansion from start time
182
iter = croniter('0 0 */7 * *', start_time=datetime(2024, 7, 11), expand_from_start_time=True)
183
```
184

185
[Advanced Features](./advanced-features.md)
186

187
## Types
188

189
### Exception Classes
190

191
```python { .api }
192
class CroniterError(ValueError):
193
    """General top-level Croniter base exception"""
194

195
class CroniterBadCronError(CroniterError):
196
    """Syntax, unknown value, or range error within a cron expression"""
197
    
198
class CroniterBadDateError(CroniterError):
199
    """Unable to find next/prev timestamp match"""
200
    
201
class CroniterBadTypeRangeError(TypeError):
202
    """Type error for range operations"""
203
    
204
class CroniterNotAlphaError(CroniterBadCronError):
205
    """Cron syntax contains an invalid day or month abbreviation"""
206
    
207
class CroniterUnsupportedSyntaxError(CroniterBadCronError):
208
    """Valid cron syntax, but likely to produce inaccurate results"""
209
```
210

211
### Constants
212

213
```python { .api }
214
MINUTE_FIELD: int = 0
215
HOUR_FIELD: int = 1
216
DAY_FIELD: int = 2
217
MONTH_FIELD: int = 3
218
DOW_FIELD: int = 4  # Day of week field
219
SECOND_FIELD: int = 5
220
YEAR_FIELD: int = 6
221
OVERFLOW32B_MODE: bool  # 32-bit overflow detection flag
222
UTC_DT  # UTC timezone object
223

224
# Field tuple constants for different cron formats
225
UNIX_FIELDS: tuple  # (MINUTE_FIELD, HOUR_FIELD, DAY_FIELD, MONTH_FIELD, DOW_FIELD)
226
SECOND_FIELDS: tuple  # (MINUTE_FIELD, HOUR_FIELD, DAY_FIELD, MONTH_FIELD, DOW_FIELD, SECOND_FIELD)
227
YEAR_FIELDS: tuple  # (MINUTE_FIELD, HOUR_FIELD, DAY_FIELD, MONTH_FIELD, DOW_FIELD, SECOND_FIELD, YEAR_FIELD)
228

229
# Cron expression length constants
230
UNIX_CRON_LEN: int = 5    # Standard 5-field cron format
231
SECOND_CRON_LEN: int = 6  # 6-field cron format with seconds
232
YEAR_CRON_LEN: int = 7    # 7-field cron format with seconds and year
233
```
234

235
### Utility Functions
236

237
```python { .api }
238
def datetime_to_timestamp(d) -> float:
239
    """Convert datetime object to UNIX timestamp"""
240
```