{"id":34020470,"url":"https://github.com/siddarth-patil/aws-croniter","last_synced_at":"2026-04-07T15:32:10.334Z","repository":{"id":269564908,"uuid":"892848623","full_name":"siddarth-patil/aws-croniter","owner":"siddarth-patil","description":"A Python utility for AWS cron expressions. Validate and parse AWS EventBridge cron expressions seamlessly.","archived":false,"fork":false,"pushed_at":"2025-11-03T16:58:42.000Z","size":110,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-02T13:33:02.178Z","etag":null,"topics":["aws","aws-cron","aws-eventbridge","aws-eventbridge-scheduler","eventbridge-scheduler"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siddarth-patil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-22T22:34:44.000Z","updated_at":"2025-11-03T19:09:40.000Z","dependencies_parsed_at":"2025-02-05T20:37:13.840Z","dependency_job_id":"05e93492-0937-4c77-9395-b8bd9198ff52","html_url":"https://github.com/siddarth-patil/aws-croniter","commit_stats":null,"previous_names":["siddarth-patil/aws-croniter"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/siddarth-patil/aws-croniter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddarth-patil%2Faws-croniter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddarth-patil%2Faws-croniter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddarth-patil%2Faws-croniter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddarth-patil%2Faws-croniter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siddarth-patil","download_url":"https://codeload.github.com/siddarth-patil/aws-croniter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siddarth-patil%2Faws-croniter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31518492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cron","aws-eventbridge","aws-eventbridge-scheduler","eventbridge-scheduler"],"created_at":"2025-12-13T15:02:14.719Z","updated_at":"2026-04-07T15:32:10.318Z","avatar_url":"https://github.com/siddarth-patil.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Croniter\n\nAWS Croniter is a Python package for parsing, validating, and calculating occurrences of AWS EventBridge cron\nexpressions. AWS cron expressions are a powerful way to schedule events, but they differ from standard Unix cron syntax.\nThis library makes it easy to work\nwith [AWS-specific cron](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html#eb-cron-expressions)\nschedules programmatically.\n\n---\n\n![PyPI](https://img.shields.io/pypi/v/aws-croniter)\n[![PyPI Downloads](https://static.pepy.tech/badge/aws-croniter)](https://pepy.tech/projects/aws-croniter)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-croniter)\n[![GitHub stars](https://img.shields.io/github/stars/siddarth-patil/aws-croniter)](https://github.com/siddarth-patil/aws-croniter/stargazers)\n![Tests](https://github.com/siddarth-patil/aws-croniter/actions/workflows/tests.yml/badge.svg)\n\n---\n\n## Table of Contents\n\n1. [Inspiration](#inspiration)\n2. [Features](#features)\n3. [Installation](#installation)\n4. [Usage](#usage)\n    - [AWS Cron Expression Example](#aws-cron-expression-example)\n    - [Handling Invalid Cron Expressions](#handling-invalid-cron-expressions)\n    - [Fetch Next Occurrence](#fetching-the-next-occurrence)\n    - [Fetch Previous Occurrence](#fetching-the-previous-occurrence)\n    - [Fetch All Schedules in Range](#fetch-all-schedules-in-range)\n    - [Get Final Execution Time](#get-final-execution-time)\n5. [Contributing](#contributing)\n6. [License](#license)\n7. [Contact](#contact)\n\n---\n\n## Inspiration\n\nAWS Croniter was inspired by two existing packages, [\n`aws-cron-expression-validator`](https://github.com/grumBit/aws_cron_expression_validator) and [\n`pyawscron`](https://github.com/pitchblack408/pyawscron), which serve similar purposes. The\n`aws-cron-expression-validator` package focuses solely on validating AWS cron expressions, while `pyawscron` provides\nfunctionality for parsing and calculating schedules such as next and previous occurrences. However, both packages had\nlimitations, and users often needed to install and integrate both packages to work effectively with AWS cron schedules.\nAWS Croniter was developed to address these issues by combining the features of both packages into a single, robust\nsolution that also provides an improved and comprehensive tool for working with AWS cron expressions.\n\n---\n\n## Features\n\n- Validate AWS cron expressions against AWS EventBridge syntax.\n- Parse and interpret cron rules with detailed validation error messages.\n- Compute:\n    - Next and previous occurrence times for a given schedule.\n    - All occurrences of a schedule between two given dates.\n    - Final execution time between two given dates (optimized for performance).\n- Handle special AWS cron syntax (e.g., `?`, `L`, `W`, `#`) and aliases for months (`JAN`, `FEB`, ...) and days of the\n  week (`SUN`, `MON`, ...).\n\n---\n\n## Installation\n\nInstall the package via pip:\n\n```bash\npip install aws-croniter\n```\n\n---\n\n## Usage\n\n### **AWS Cron Expression Example**\n\n```python\nfrom aws_croniter import AwsCroniter\n\ncron_expression = \"0 12 15 * ? 2023\"  # AWS cron syntax\naws_cron = AwsCroniter(cron_expression)\n```\n\n---\n\n### **Handling Invalid Cron Expressions**\n\nWhen an invalid AWS cron expression is passed, `AwsCroniter` raises specific exceptions indicating the nature of the\nerror:\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom aws_croniter.exceptions import AwsCroniterExpressionError\n\ntry:\n    invalid_cron = \"0 18 ? * MON-FRI\"  # Missing fields\n    AwsCroniter(invalid_cron)\nexcept AwsCroniterExpressionError as e:\n    print(f\"Invalid cron expression: {e}\")\n# Output: Invalid cron expression: Incorrect number of values in '0 18 ? * MON-FRI'. 6 required, 5 provided.\n```\n\n---\n\n### **Fetching the Next Occurrence**\n\nThe `get_next` method retrieves the next occurrence(s) of the cron schedule from a specified date. This method\nalways returns a list with `n` items and sets the items to `None` if no valid occurrences are found.\n\n#### **Basic Usage**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 12, 14, tzinfo=timezone.utc)\nnext_occurrence = aws_cron.get_next(start_date)\n\nprint(next_occurrence)\n# Output: [datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n#### **Retrieving Multiple Occurrences (n \u003e 1)**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 9, 14, tzinfo=timezone.utc)\n\n# Fetch the next 3 occurrences\nnext_occurrences = aws_cron.get_next(start_date, n=3)\n\nprint(next_occurrences)\n# Output: [datetime.datetime(2023, 9, 15, 12, 0, tzinfo=datetime.timezone.utc),\n#          datetime.datetime(2023, 10, 15, 12, 0, tzinfo=datetime.timezone.utc),\n#          datetime.datetime(2023, 11, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n#### **Using the Inclusive Parameter**\n\nSetting `inclusive=True` includes the start date in the results if it matches the schedule. The default is `False`.\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 12, 15, 12, 0,\n                      tzinfo=timezone.utc)\n# Include the starting date in the results\nnext_occurrence_inclusive = aws_cron.get_next(start_date, inclusive=True)\n\nprint(next_occurrence_inclusive)\n# Output: [datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n---\n\n### **Fetching the Previous Occurrence**\n\nThe `get_prev` method retrieves the previous occurrence(s) of the cron schedule from a specified date. This method\nalways returns a list with `n` items and sets the items to `None` if no valid occurrences are found.\n\n#### **Basic Usage**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 12, 14, tzinfo=timezone.utc)\nprev_occurrence = aws_cron.get_prev(start_date)\n\nprint(prev_occurrence)\n# Output: [datetime.datetime(2023, 11, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n#### **Retrieving Multiple Occurrences (n \u003e 1)**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 12, 14, tzinfo=timezone.utc)\n\n# Fetch the previous 2 occurrences\nprev_occurrences = aws_cron.get_prev(start_date, n=2)\n\nprint(prev_occurrences)\n# Output: [datetime.datetime(2023, 11, 15, 12, 0, tzinfo=datetime.timezone.utc),\n#          datetime.datetime(2023, 10, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n#### **Using the Inclusive Parameter**\n\nSetting `inclusive=True` includes the start date in the results if it matches the schedule. The default is `False`.\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Starting datetime\nstart_date = datetime(2023, 12, 15, 12, 0,\n                      tzinfo=timezone.utc)\n# Include the starting date in the results\nprev_occurrence_inclusive = aws_cron.get_prev(start_date, inclusive=True)\n\nprint(prev_occurrence_inclusive)\n# Output: [datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n---\n\n### **Fetch All Schedules in Range**\n\nThe `get_all_schedule_bw_dates` method retrieves all occurrences of the cron schedule between two specified dates.\n\n#### **Basic Usage**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Define the date range\nfrom_date = datetime(2023, 11, 14, tzinfo=timezone.utc)\nto_date = datetime(2023, 12, 31, tzinfo=timezone.utc)\n\n# Fetch all occurrences in the range\nall_occurrences = aws_cron.get_all_schedule_bw_dates(from_date, to_date)\n\nprint(all_occurrences)\n# Output: [datetime.datetime(2023, 11, 15, 12, 0, tzinfo=datetime.timezone.utc),\n#          datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n#### **Excluding Start and End Dates**\n\nSetting `exclude_ends=True` omits occurrences that match the start and end dates. The default is `False`.\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Define the date range\nfrom_date = datetime(2023, 11, 14, tzinfo=timezone.utc)\nto_date = datetime(2023, 12, 31, tzinfo=timezone.utc)\n# Exclude the start and end dates from the results\nall_occurrences_exclude_ends = aws_cron.get_all_schedule_bw_dates(from_date, to_date, exclude_ends=True)\n\nprint(all_occurrences_exclude_ends)\n# Output: [datetime.datetime(2023, 11, 15, 12, 0, tzinfo=datetime.timezone.utc), \n#          datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)]\n```\n\n---\n\n### **Get Final Execution Time**\n\nThe `get_final_execution_time` method retrieves the final execution datetime between two specified dates.\nThe `to_date` is exclusive, meaning if it exactly matches the cron expression, it will not be included\nin the result. Only executions strictly before `to_date` will be returned.\n\n#### **Basic Usage**\n\n```python\nfrom aws_croniter import AwsCroniter\nfrom datetime import datetime, timezone\n\n# AWS cron expression\ncron_expression = \"0 12 15 * ? 2023\"\naws_cron = AwsCroniter(cron_expression)\n\n# Define the date range\nfrom_date = datetime(2023, 11, 14, tzinfo=timezone.utc)\nto_date = datetime(2023, 12, 31, tzinfo=timezone.utc)\n\n# Get the final execution time in the range\nfinal_execution = aws_cron.get_final_execution_time(from_date, to_date)\n\nprint(final_execution)\n# Output: datetime.datetime(2023, 12, 15, 12, 0, tzinfo=datetime.timezone.utc)\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please read the [contributing guidelines](docs/CONTRIBUTING.md) first.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contact\n\nFor any questions or suggestions, please open an issue or contact the maintainer\nat [hello@techwithsid.com](mailto:hello@techwithsid.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddarth-patil%2Faws-croniter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiddarth-patil%2Faws-croniter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddarth-patil%2Faws-croniter/lists"}