{"id":15003,"library":"tzcron","title":"Timezone aware Cron/Quartz parser","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/bloomberg/tzcron","tags":["cron","scheduler","timezone","datetime","parsing","quartz"],"install":[{"cmd":"pip install tzcron","lang":"bash","label":"Install tzcron"}],"dependencies":[{"reason":"Required for timezone handling with `tzcron.Schedule` objects.","package":"pytz","optional":false}],"imports":[{"symbol":"tzcron","correct":"import tzcron"},{"note":"Schedule is a class within the tzcron module, not a top-level module itself.","wrong":"import Schedule","symbol":"Schedule","correct":"from tzcron import Schedule"},{"note":"pytz is an external dependency and must be imported directly, not from tzcron.","wrong":"from tzcron import pytz","symbol":"pytz","correct":"import pytz"}],"quickstart":{"code":"import tzcron\nimport pytz\nfrom datetime import datetime\n\n# Create a timezone-aware schedule for every minute (using UTC)\nschedule_utc = tzcron.Schedule(\"* * * * * *\", pytz.utc)\nprint(f\"UTC Schedule: {str(schedule_utc)}\")\n\n# Get the next 3 occurrences in UTC\nprint(\"Next 3 UTC occurrences:\")\nfor _ in range(3):\n    print(next(schedule_utc))\n\n# Create a schedule for every hour at 30 minutes past the hour, in 'America/New_York' timezone\nny_timezone = pytz.timezone('America/New_York')\nschedule_ny = tzcron.Schedule(\"30 * * * *\", ny_timezone)\nprint(f\"NY Schedule: {str(schedule_ny)}\")\n\n# Get the next occurrence for the NY schedule after a specific time\n# Use a fixed start time for consistent results in tests\nstart_time = ny_timezone.localize(datetime(2026, 4, 16, 10, 0, 0))\nprint(f\"Next NY occurrence after {start_time}: {schedule_ny.get_next_occurrence(start_time)}\")","lang":"python","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"<=1.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pytz` is installed (`pip install pytz`) and `import pytz` is present in your code before using `tzcron.Schedule`.","cause":"The `pytz` library, a required dependency for `tzcron`'s timezone functionality, has not been imported or installed.","error":"NameError: name 'pytz' is not defined"},{"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):`).","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.","error":"TypeError: 'Schedule' object is not iterable"},{"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)`.","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.","error":"ValueError: schedule is ambiguous during a DST transition: Multiple instances of this time exist."}],"ecosystem":"pypi"}