pycron

library3.2.0pypypi✓ verified 25d ago

pycron is a simple Python library for parsing cron-like expressions and determining if a given datetime matches the specified conditions. It supports standard cron formats, day names, and step values. The current version is 3.2.0, and the library is actively maintained with several releases per year.

workflow devops

pip install pycron

github ↗package ↗

INSTALL

IMPORT

SIG · PYCRON

pycron

workflowpythonv3.2.0

Install

1.5s avg

Import

17ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.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.95 runs

installs and imports cleanly · install 0.0s · import 0.018s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.016s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

is_now

✓ from pycron import is_now

has_been

✓ from pycron import has_been

Used for 'anacron' style checks to see if conditions have been met since a past datetime.

Demonstrates how to use `is_now` to check if a cron expression matches a given datetime (or the current time), and `has_been` for checking if a condition was met within a time range.

import datetime from pycron import is_now, has_been # Check if current time (or a specific datetime) matches a cron string # This example checks if it's currently every minute matches_every_minute = is_now('* * * * *') print(f"Matches every minute (current time): {matches_every_minute}") # Check for a specific time, e.g., 9:30 AM every weekday specific_dt = datetime.datetime(2023, 10, 26, 9, 30, 0) # Thursday matches_specific_time = is_now('30 9 * * 1-5', specific_dt) print(f"Matches 9:30 AM on a weekday (2023-10-26 09:30): {matches_specific_time}") # Using has_been (anacron style) # Check if '0 0 * * *' (midnight) has occurred since an hour ago now = datetime.datetime.now() one_hour_ago = now - datetime.timedelta(hours=1) midnight_occurred = has_been('0 0 * * *', one_hour_ago, now) print(f"Midnight occurred between {one_hour_ago.strftime('%H:%M')} and {now.strftime('%H:%M')}: {midnight_occurred}")

Debug

Known issues

breakingVersion 3.0.0 dropped support for Python 2.7 and Python 3.4. Users on these older Python versions must remain on `pycron < 3.0.0`.

fix

Upgrade Python to a supported version (>=3.9, <4.0) or pin `pycron` to an older version like `pycron<3.0.0`.

affects: >=3.0.0

breakingVersion 3.1.0 included updates to the DOM (Day of Month) and DOW (Day of Week) parsing logic. While intended for correctness, this might subtly change the interpretation of certain complex or edge-case cron expressions, potentially leading to different match outcomes.

fix

Thoroughly test existing cron expressions when upgrading to `pycron >= 3.1.0` to ensure continued expected behavior, especially for expressions involving specific days of the month or week combinations.

affects: >=3.1.0

gotchapycron supports both timezone-aware and naive datetime objects. However, mixing them or not consistently handling timezones can lead to unexpected matches, particularly when cron expressions refer to specific times (e.g., '0 0 * * *' for midnight). The library itself does not perform timezone conversions.

fix

Ensure that the datetime objects passed to `is_now` or `has_been` are consistently timezone-aware (preferably UTC) or consistently naive, matching the intended timezone context of your cron expressions.

affects: All versions

gotchapycron 3.x strictly requires Python versions >=3.9 and <4.0. Attempting to install or run on Python 3.8 or older, or Python 4.0 and newer (when released) without explicit support, will result in installation failures or runtime errors.

fix

Verify your Python environment meets the `>=3.9, <4.0` requirement before installing `pycron`.

affects: >=3.0.0

Errors

Common errors & fixes

ValueError: The since datetime must be before the current datetime.

The `since` datetime argument provided to `pycron.has_been` represents a point in time that is not chronologically before the `dt` (current datetime) argument. The `has_been` function requires `since` to be in the past relative to `dt`.

fix

Ensure that the `since` datetime object is strictly earlier than the `dt` (or current system) datetime object when calling `pycron.has_been`. For example, `since = dt - timedelta(hours=1)`.

ValueError: Failed to parse string to integer

A segment of the cron expression string provided to `pycron.is_now` or `pycron.has_been` could not be successfully converted into an integer, indicating invalid syntax within the expression.

fix

Review the cron expression string for any non-numeric characters in fields that expect integer values, or for malformed ranges and step values. Ensure all parts conform to standard cron expression syntax.

ModuleNotFoundError: No module named 'pycron'

The 'pycron' library has not been installed in the Python environment currently being used, or the Python interpreter cannot find the installed module.

fix

Install the library using pip: `pip install pycron`. If already installed, ensure your Python environment path is correctly configured.

NameError: name 'is_now' is not defined

This error occurs when `pycron.is_now` (or `pycron.has_been`) is called without prefixing it with `pycron.` after importing the module using `import pycron`.

fix

If you imported with `import pycron`, call the function as `pycron.is_now('expression')`. Alternatively, you can use `from pycron import is_now` to call it directly as `is_now('expression')`.

Upgrade

Version history

3.2.0latest on PyPI · released Jun 5, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kipe/pycron ↗

packagehttps://pypi.org/project/pycron/ ↗