# oncalendar
[](https://github.com/cuu508/oncalendar/actions/workflows/pytest.yml)
A systemd [OnCalendar expression](https://www.man7.org/linux/man-pages/man7/systemd.time.7.html#CALENDAR_EVENTS)
parser and evaluator. Requires Python 3.10+.
oncalendar is written for and being used in [Healthchecks](https://github.com/healthchecks/healthchecks/)
(a scheduled task monitoring service).
This package provides three iterators:
* **oncalendar.BaseIterator(expression: str, start: datime)**: supports expressions
without timezone (example: "Mon, 12:34"). Accepts both naive and timezone-aware
datetimes as the start time.
* **oncalendar.TzIterator(expression: str, start: datetime)**: supports expressions
with and without timezone. (example: "Mon, 12:34 Europe/Riga"). Requires the start
datetime to be timezone-aware.
* **oncalendar.OnCalendar(expressions:str, start: datetime)**: supports multiple
expressions with or without timezones, separated by newlines. Requires the start
datetime to be timezone-aware. Example:
```
2020-01-01
12:34 Europe/Riga
```
## Installation
```
pip install oncalendar
```
## Usage
```python
from datetime import datetime
from oncalendar import BaseIterator
it = BaseIterator("Mon, 12:34", datetime.now())
for x in range(0, 10):
print(next(it))
```
Produces:
```
2023-12-11 12:34:00
2023-12-18 12:34:00
2023-12-25 12:34:00
2024-01-01 12:34:00
2024-01-08 12:34:00
2024-01-15 12:34:00
2024-01-22 12:34:00
2024-01-29 12:34:00
2024-02-05 12:34:00
2024-02-12 12:34:00
```
If oncalendar receives an invalid expression, it raises `oncalendar.OnCalendarError`
exception:
```python
from datetime import datetime
from oncalendar import BaseIterator
BaseIterator("Mon, 123:456", datetime.now())
```
Produces:
```
oncalendar.OnCalendarError: Bad hour
```
If oncalendar hits year 2200 while iterating, it stops iteration by raising
`StopIteration`:
```python
from datetime import datetime
from oncalendar import BaseIterator
# 2199 is not leap year, and we stop at 2200
print(next(BaseIterator("2199-2-29", datetime.now())))
```
Produces:
```
StopIteration
```
## Known Limitations
* Does not support decimals in the second field.
Raw data
{
"_id": null,
"home_page": "https://github.com/cuu508/oncalendar",
"name": "oncalendar",
"maintainer": "",
"docs_url": null,
"requires_python": ">= 3.10",
"maintainer_email": "",
"keywords": "systemd,oncalendar,calendar,schedule",
"author": "P\u0113teris Caune",
"author_email": "cuu508@monkeyseemonkeydo.lv",
"download_url": "https://files.pythonhosted.org/packages/d2/16/0a632a870a4f6916c91e95a717391a9c0eaaa28a3d2402704551861b118a/oncalendar-1.1.tar.gz",
"platform": "any",
"description": "# oncalendar\n\n[](https://github.com/cuu508/oncalendar/actions/workflows/pytest.yml)\n\nA systemd [OnCalendar expression](https://www.man7.org/linux/man-pages/man7/systemd.time.7.html#CALENDAR_EVENTS)\nparser and evaluator. Requires Python 3.10+.\n\noncalendar is written for and being used in [Healthchecks](https://github.com/healthchecks/healthchecks/)\n(a scheduled task monitoring service).\n\nThis package provides three iterators:\n\n* **oncalendar.BaseIterator(expression: str, start: datime)**: supports expressions\n without timezone (example: \"Mon, 12:34\"). Accepts both naive and timezone-aware\n datetimes as the start time.\n* **oncalendar.TzIterator(expression: str, start: datetime)**: supports expressions\n with and without timezone. (example: \"Mon, 12:34 Europe/Riga\"). Requires the start\n datetime to be timezone-aware.\n* **oncalendar.OnCalendar(expressions:str, start: datetime)**: supports multiple\n expressions with or without timezones, separated by newlines. Requires the start\n datetime to be timezone-aware. Example:\n\n ```\n 2020-01-01\n 12:34 Europe/Riga\n ```\n\n## Installation\n\n```\npip install oncalendar\n```\n\n## Usage\n\n```python\nfrom datetime import datetime\nfrom oncalendar import BaseIterator\n\nit = BaseIterator(\"Mon, 12:34\", datetime.now())\nfor x in range(0, 10):\n print(next(it))\n```\n\nProduces:\n\n```\n2023-12-11 12:34:00\n2023-12-18 12:34:00\n2023-12-25 12:34:00\n2024-01-01 12:34:00\n2024-01-08 12:34:00\n2024-01-15 12:34:00\n2024-01-22 12:34:00\n2024-01-29 12:34:00\n2024-02-05 12:34:00\n2024-02-12 12:34:00\n```\n\nIf oncalendar receives an invalid expression, it raises `oncalendar.OnCalendarError`\nexception:\n\n```python\nfrom datetime import datetime\nfrom oncalendar import BaseIterator\n\nBaseIterator(\"Mon, 123:456\", datetime.now())\n```\n\nProduces:\n\n```\noncalendar.OnCalendarError: Bad hour\n```\n\nIf oncalendar hits year 2200 while iterating, it stops iteration by raising\n`StopIteration`:\n\n```python\nfrom datetime import datetime\nfrom oncalendar import BaseIterator\n\n# 2199 is not leap year, and we stop at 2200\nprint(next(BaseIterator(\"2199-2-29\", datetime.now())))\n```\n\nProduces:\n\n```\nStopIteration\n```\n\n## Known Limitations\n\n* Does not support decimals in the second field.\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Systemd OnCalendar expression parser and evaluator",
"version": "1.1",
"project_urls": {
"Changelog": "https://github.com/cuu508/oncalendar/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/cuu508/oncalendar"
},
"split_keywords": [
"systemd",
"oncalendar",
"calendar",
"schedule"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2160a632a870a4f6916c91e95a717391a9c0eaaa28a3d2402704551861b118a",
"md5": "c61394fcd6b8854ceeb5f0710c930226",
"sha256": "3122aa811786c313568a53745015729aa650e35054b689c08b6db4b1ee891287"
},
"downloads": -1,
"filename": "oncalendar-1.1.tar.gz",
"has_sig": false,
"md5_digest": "c61394fcd6b8854ceeb5f0710c930226",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">= 3.10",
"size": 8650,
"upload_time": "2024-03-14T14:35:43",
"upload_time_iso_8601": "2024-03-14T14:35:43.164053Z",
"url": "https://files.pythonhosted.org/packages/d2/16/0a632a870a4f6916c91e95a717391a9c0eaaa28a3d2402704551861b118a/oncalendar-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-14 14:35:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cuu508",
"github_project": "oncalendar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "oncalendar"
}
JSON
