tzcron

library1.0.0pypiunverified

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.

serialization

pip install tzcron

INSTALL

IMPORT

SIG · TZCRON

tzcron

serializationenv1.0.0

Install

1.8s avg

Import

31ms

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.0 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.030s · 21.5MB

glibc

py 3.10–3.910 runs

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

20MB installed

● package 20MB

Code

Verified usage

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

tzcron

✓ import tzcron

Schedule

✓ from tzcron import Schedule

✗ import Schedule

Schedule is a class within the tzcron module, not a top-level module itself.

pytz

✓ import pytz

✗ from tzcron import pytz

pytz is an external dependency and must be imported directly, not from tzcron.

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

Debug

Known issues

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

affects: <=1.0.0

gotchaWhen 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)`.

affects: All

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

affects: All

Errors

Common errors & fixes

NameError: name 'pytz' is not defined

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

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.

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

Upgrade

Version history

1.0.0latest on PyPI · released Sep 25, 2016

Audit

Dependencies

pytzrequiredRequired for timezone handling with `tzcron.Schedule` objects.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.