Timezone aware Cron/Quartz parser

1.0.0 · active · verified Thu Apr 16

tzcron is a Python library that provides a way to define schedules using cron/quartz expressions and attach them to specific timezones. It allows users to iterate over a schedule object to get future time occurrences, serving as a powerful cron parser without implementing scheduling capabilities itself. The current version is 1.0.0. The library appears to have a stable, though infrequent, release cadence, with the last update in 2016.

Common errors

```
NameError: name 'pytz' is not defined
```
cause The `pytz` library, a required dependency for `tzcron`'s timezone functionality, has not been imported or installed.

fix Ensure `pytz` is installed (`pip install pytz`) and `import pytz` is present in your code before using `tzcron.Schedule`.
```
TypeError: 'Schedule' object is not iterable
```
cause While `tzcron.Schedule` objects are iterable to yield occurrences, this error might indicate a misunderstanding of how to access the next event (e.g., trying to directly index it) or an attempt to use it in a context not expecting an iterator.

fix To get the next occurrence, use `next(schedule_object)` or `schedule_object.get_next_occurrence()`. If iterating, ensure you handle potential infinite sequences with a loop limit (e.g., `itertools.islice` or a `for i in range(n):`).
```
ValueError: schedule is ambiguous during a DST transition: Multiple instances of this time exist.
```
cause During a Daylight Saving Time (DST) 'fall back' transition, the same local clock time may occur twice. If a cron expression falls into this ambiguous period, `tzcron` needs guidance on which occurrence to choose.

fix Use the `ambiguity_handler` parameter when creating the `Schedule` object, providing a callable that resolves the ambiguity. For example, `tzcron.Schedule(..., ambiguity_handler=tzcron.use_first_occurrence_of_ambiguous_time)` or `tzcron.Schedule(..., ambiguity_handler=tzcron.use_last_occurrence_of_ambiguous_time)`.

Warnings

gotcha The tzcron library has not been updated since September 2016. While it is stable, this long period of inactivity may indicate a lack of ongoing maintenance, potential compatibility issues with newer Python versions (beyond 3.5), or unpatched security vulnerabilities in its dependencies.
Fix: Thoroughly test with your target Python environment and consider the implications of using an unmaintained library. Review dependencies like `pytz` for their maintenance status and alternatives like `zoneinfo`.
gotcha When creating a `Schedule` object, `tzcron` requires a timezone object, typically from the `pytz` library. Forgetting to import `pytz` or attempting to use a naive datetime object will lead to errors, as `tzcron` is designed for timezone-aware operations.
Fix: Always ensure `import pytz` is present and pass a valid `pytz.timezone` object to `tzcron.Schedule`. For example: `tzcron.Schedule('0 0 * * *', pytz.utc)`.
gotcha While `tzcron` handles timezone-aware parsing and DST transitions, the actual execution environment of a cron job (e.g., in `crontab`) might still introduce issues related to `PATH`, `SHELL`, and environment variables. `tzcron` only provides the *schedule*, not the runtime environment.
Fix: When deploying actual cron jobs based on `tzcron`'s output, ensure the `crontab` entry specifies full paths to executables and scripts, sets necessary environment variables, and redirects output for debugging. For example, explicitly setting `PATH` within the `crontab` file.

Install

pip install tzcron Install tzcron

Imports

tzcron
```
import tzcron
```
Schedule
wrong:
```
import Schedule
```
correct:
```
from tzcron import Schedule
```
Schedule is a class within the tzcron module, not a top-level module itself.
pytz
wrong:
```
from tzcron import pytz
```
correct:
```
import pytz
```
pytz is an external dependency and must be imported directly, not from tzcron.

Quickstart

This quickstart demonstrates how to create timezone-aware cron schedules using `tzcron`. It shows how to initialize a schedule with a cron expression and a `pytz` timezone, and then retrieve future occurrences by iterating or using `get_next_occurrence`.

import tzcron
import pytz
from datetime import datetime

# Create a timezone-aware schedule for every minute (using UTC)
schedule_utc = tzcron.Schedule("* * * * * *", pytz.utc)
print(f"UTC Schedule: {str(schedule_utc)}")

# Get the next 3 occurrences in UTC
print("Next 3 UTC occurrences:")
for _ in range(3):
    print(next(schedule_utc))

# Create a schedule for every hour at 30 minutes past the hour, in 'America/New_York' timezone
ny_timezone = pytz.timezone('America/New_York')
schedule_ny = tzcron.Schedule("30 * * * *", ny_timezone)
print(f"NY Schedule: {str(schedule_ny)}")

# Get the next occurrence for the NY schedule after a specific time
# Use a fixed start time for consistent results in tests
start_time = ny_timezone.localize(datetime(2026, 4, 16, 10, 0, 0))
print(f"Next NY occurrence after {start_time}: {schedule_ny.get_next_occurrence(start_time)}")

view raw JSON →