<p align="center">
<img src="https://raw.githubusercontent.com/Sonic0/cron-converter/main/logo.png" title="Cron-converter">
</p>
Cron-converter provides a Cron string parser ( from string/lists to string/lists ) and iteration for the datetime object with a cron like format.<br>
This project would be a transposition in Python of JS [cron-converter](https://github.com/roccivic/cron-converter) by [roccivic](https://github.com/roccivic).
[](https://github.com/Sonic0/cron-converter/blob/master/LICENCE)
[](https://codebeat.co/projects/github-com-sonic0-cron-converter-main)
## Install
#### Pip
```bash
pip install cron-converter
```
## Use
```python
from cron_converter import Cron
```
### Create a new instance
```python
cron_instance = Cron()
```
or
```python
cron_instance = Cron('*/10 9-17 1 * *')
```
or (with constructor options)
```python
cron_instance = Cron('*/10 9-17 1 * *', {
'output_weekday_names': True,
'output_month_names': True
})
```
### Parse a cron string
```python
# Every 10 mins between 9am and 5pm on the 1st of every month
# In the case of the second or third creation method this step is not required
cron_instance.from_string('*/10 9-17 1 * *')
# Prints: '*/10 9-17 1 * *'
print(cron_instance.to_string())
# Alternatively, you could print directly the object obtaining the same result:
# print(cron_instance) # Prints: '*/10 9-17 1 * *'
# Prints:
# [
# [ 0, 10, 20, 30, 40, 50 ],
# [ 9, 10, 11, 12, 13, 14, 15, 16, 17 ],
# [ 1 ],
# [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ],
# [ 0, 1, 2, 3, 4, 5, 6 ]
# ]
print(cron_instance.to_list())
```
### Parse an Array
```python
cron_instance.from_list([[0], [1], [1], [5], [0,2,4,6]])
# Prints: '0 1 1 5 */2'
print(cron_instance.to_string())
```
### Constructor options
Possible options:
- output_weekday_names: false (default)
- output_month_names: false (default)
- output_hashes: false (default)
#### output_weekday_names and output_month_names
```python
cron_instance = Cron(None, {
'output_weekday_names': True,
'output_month_names': True
})
cron_instance.from_string('*/5 9-17/2 * 1-3 1-5')
# Prints: '*/5 9-17/2 * JAN-MAR MON-FRI'
print(cron_instance)
```
or
```python
cron_instance = Cron('*/5 9-17/2 * 1-3 1-5', {
'output_weekday_names': True,
'output_month_names': True
})
# Prints: '*/5 9-17/2 * JAN-MAR MON-FRI'
print(cron_instance)
```
#### output_hashes
```python
cron_instance = Cron('*/5 9-17/2 * 1-3 1-5', {
'output_hashes': True
})
# Prints: 'H/5 H(9-17)/2 H 1-3 1-5'
print(cron_instance.to_string())
```
### Get the schedule execution times. Example with raw Datetime
```python
# Parse a string to init a schedule
cron_instance.from_string('*/5 * * * *')
# Raw datetime without timezone info (not aware)
reference = datetime.now()
# Get the iterator, initialised to now
schedule = cron_instance.schedule(reference)
# Calls to .next() and .prev()
# return a Datetime object
# Examples with time now: '2021-01-01T09:32:00
# Prints: '2021-01-01T09:35:00'
print(schedule.next().isoformat())
# Prints: '2021-01-01T09:40:00'
print(schedule.next().isoformat())
# Reset
schedule.reset()
# Prints: '2021-01-01T09:30:00'
print(schedule.prev().isoformat())
# Prints: '2021-01-01T09:25:00'
print(schedule.prev().isoformat())
```
## About DST
Be sure to init your cron-converter instance with a TZ aware datetime for this to work!
A Scheduler has two optional mutually exclusive arguments: `start_date` or `timezone_str`.
By default (no parameters), a Scheduler start count with a UTC datetime ( _utcnow()_ ) if you not specify any `start_date` datetime object.
If you provide `timezone_str` the Scheduler will start count from a localized now datetime ( _datetime.now(tz_object)_ ).
Example starting from localized now datetime
```python
from cron_converter import Cron
cron = Cron('0 0 * * *')
schedule = cron.schedule(timezone_str='Europe/Rome')
# Prints: result datetime + utc offset
print(schedule.next())
```
Example using pytz:
```python
from pytz import timezone
from datetime import datetime
from cron_converter import Cron
tz = timezone('Europe/Rome')
local_date = tz.localize(datetime(2021, 1, 1))
cron = Cron('0 0 * * *')
schedule = cron.schedule(start_date=local_date)
next_schedule = schedule.next()
next_next_schedule = schedule.next()
# Prints: '2021-01-01T00:00:00+01:00'
print(next_schedule.isoformat())
# Prints: '2021-01-02T00:00:00+01:00'
print(next_next_schedule.isoformat())
```
Example using python_dateutil:
```python
import dateutil.tz
from datetime import datetime
from cron_converter import Cron
tz = dateutil.tz.gettz('Asia/Tokyo')
local_date = datetime(2021, 1, 1, tzinfo=tz)
cron = Cron('0 0 * * *')
schedule = cron.schedule(start_date=local_date)
next_schedule = schedule.next()
next_next_schedule = schedule.next()
# Prints: '2021-01-01T00:00:00+09:00'
print(next_schedule.isoformat())
# Prints: '2021-01-02T00:00:00+09:00'
print(next_next_schedule.isoformat())
```
## About Cron schedule times frequency
It's possible to compare the Cron object schedules frequency. Thanks [@zevaverbach](https://github.com/zevaverbach).
```python
# Hours
Cron('0 1 * * 1-5') == Cron('0 2 * * 1-5') # True
Cron('0 1,2,3 * * 1-5') > Cron('0 1,23 * * 1-5') # True
# Minutes
Cron('* 1 * * 1-5') == Cron('0-59 1 * * 1-5') # True
Cron('1-30 1 * * 1-5') > Cron('1-29 1 * * 1-5') # True
# Days
Cron('* 1 1 * 1-5') == Cron('0-59 1 2 * 1-5') # True
Cron('* 1 1,2 * 1-5') > Cron('* 1 6 * 1-5') # True
# Month
Cron('* 1 1 11 1-5') == Cron('* 1 1 1 1-5') # True
Cron('* 1 6 * 1-5') > Cron('* 1 6 1 1-5') # True
# WeekDay
Cron('* 1 1 11 *') == Cron('* 1 1 11 0-6') # True
Cron('* 1 6 * 1-5') > Cron('* 1 6 * 1-4') # True
```
## About seconds repeats
Cron-converter is NOT able to do second repetition crontabs form.
## About datetime objects validation
Cron can also validate datetime objects (datetime and date).
```python
Cron("* * 10 * *").validate(datetime(2022, 1, 10, 1, 9)) # True
Cron("* * 12 * *").validate(datetime(2022, 1, 10, 1, 9)) # False
```
A datetime object can also be validated with the `in` operator
```python
datetime(2024, 3, 19, 15, 55) in Cron('*/5 9-17/2 * 1-3 1-5') # True
```
## Develop & Tests
```bash
git clone https://github.com/Sonic0/cron-converter
cd cron-converter
...
python -m unittest discover -s tests/unit
python -m unittest discover -s tests/integration
```
## Project info
This repo is part of a projects group, called _Cron-Converter_.
Its related repositories:
- [local-crontab](https://github.com/Sonic0/local-crontab)
- [local-crontab-ansible-filter](https://github.com/Sonic0/local-crontab-ansible-filter)
- [local-crontab-serverless-infrastructure](https://github.com/Sonic0/local-crontab-serverless-infrastructure)
- [local-crontab-web-converter](https://github.com/Sonic0/local-crontab-web-converter)
Raw data
{
"_id": null,
"home_page": "https://github.com/Sonic0/cron-converter",
"name": "cron-converter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cron",
"author": "Andrea Salvatori",
"author_email": "andrea.salvatori92@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/3e/b6b6e09adaa6b5d1eb2c7d91df542b57f2131ed2df592f344da1a5085438/cron-converter-1.1.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/Sonic0/cron-converter/main/logo.png\" title=\"Cron-converter\">\n</p>\n\nCron-converter provides a Cron string parser ( from string/lists to string/lists ) and iteration for the datetime object with a cron like format.<br>\nThis project would be a transposition in Python of JS [cron-converter](https://github.com/roccivic/cron-converter) by [roccivic](https://github.com/roccivic). \n\n[](https://github.com/Sonic0/cron-converter/blob/master/LICENCE)\n\n[](https://codebeat.co/projects/github-com-sonic0-cron-converter-main)\n\n## Install\n\n#### Pip\n```bash\npip install cron-converter\n```\n\n## Use\n```python\nfrom cron_converter import Cron\n```\n\n### Create a new instance\n```python\ncron_instance = Cron()\n```\nor\n```python\ncron_instance = Cron('*/10 9-17 1 * *')\n```\nor (with constructor options)\n```python\ncron_instance = Cron('*/10 9-17 1 * *', {\n 'output_weekday_names': True,\n 'output_month_names': True\n})\n```\n\n### Parse a cron string\n```python\n# Every 10 mins between 9am and 5pm on the 1st of every month\n# In the case of the second or third creation method this step is not required\ncron_instance.from_string('*/10 9-17 1 * *')\n\n# Prints: '*/10 9-17 1 * *'\nprint(cron_instance.to_string())\n# Alternatively, you could print directly the object obtaining the same result:\n# print(cron_instance) # Prints: '*/10 9-17 1 * *'\n\n# Prints:\n# [\n# [ 0, 10, 20, 30, 40, 50 ],\n# [ 9, 10, 11, 12, 13, 14, 15, 16, 17 ],\n# [ 1 ],\n# [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ],\n# [ 0, 1, 2, 3, 4, 5, 6 ]\n# ]\nprint(cron_instance.to_list())\n```\n\n### Parse an Array\n```python\ncron_instance.from_list([[0], [1], [1], [5], [0,2,4,6]])\n\n# Prints: '0 1 1 5 */2'\nprint(cron_instance.to_string())\n```\n\n### Constructor options\nPossible options:\n- output_weekday_names: false (default)\n- output_month_names: false (default)\n- output_hashes: false (default)\n\n#### output_weekday_names and output_month_names\n```python\ncron_instance = Cron(None, {\n 'output_weekday_names': True,\n 'output_month_names': True\n})\ncron_instance.from_string('*/5 9-17/2 * 1-3 1-5')\n# Prints: '*/5 9-17/2 * JAN-MAR MON-FRI'\nprint(cron_instance)\n```\nor\n```python\ncron_instance = Cron('*/5 9-17/2 * 1-3 1-5', {\n 'output_weekday_names': True,\n 'output_month_names': True\n})\n# Prints: '*/5 9-17/2 * JAN-MAR MON-FRI'\nprint(cron_instance)\n```\n\n#### output_hashes\n```python\ncron_instance = Cron('*/5 9-17/2 * 1-3 1-5', {\n 'output_hashes': True\n})\n# Prints: 'H/5 H(9-17)/2 H 1-3 1-5'\nprint(cron_instance.to_string())\n```\n\n### Get the schedule execution times. Example with raw Datetime\n```python\n# Parse a string to init a schedule\ncron_instance.from_string('*/5 * * * *')\n\n# Raw datetime without timezone info (not aware)\nreference = datetime.now()\n# Get the iterator, initialised to now\nschedule = cron_instance.schedule(reference)\n\n# Calls to .next() and .prev()\n# return a Datetime object\n\n# Examples with time now: '2021-01-01T09:32:00\n# Prints: '2021-01-01T09:35:00'\nprint(schedule.next().isoformat())\n# Prints: '2021-01-01T09:40:00'\nprint(schedule.next().isoformat())\n\n# Reset\nschedule.reset()\n\n# Prints: '2021-01-01T09:30:00'\nprint(schedule.prev().isoformat())\n# Prints: '2021-01-01T09:25:00'\nprint(schedule.prev().isoformat())\n```\n\n## About DST\nBe sure to init your cron-converter instance with a TZ aware datetime for this to work!\n\nA Scheduler has two optional mutually exclusive arguments: `start_date` or `timezone_str`. \nBy default (no parameters), a Scheduler start count with a UTC datetime ( _utcnow()_ ) if you not specify any `start_date` datetime object. \nIf you provide `timezone_str` the Scheduler will start count from a localized now datetime ( _datetime.now(tz_object)_ ). \n\nExample starting from localized now datetime\n```python\nfrom cron_converter import Cron\n\ncron = Cron('0 0 * * *')\nschedule = cron.schedule(timezone_str='Europe/Rome')\n# Prints: result datetime + utc offset\nprint(schedule.next())\n```\n\nExample using pytz:\n```python\nfrom pytz import timezone\nfrom datetime import datetime\nfrom cron_converter import Cron\n\ntz = timezone('Europe/Rome')\nlocal_date = tz.localize(datetime(2021, 1, 1))\ncron = Cron('0 0 * * *')\nschedule = cron.schedule(start_date=local_date)\nnext_schedule = schedule.next()\nnext_next_schedule = schedule.next()\n# Prints: '2021-01-01T00:00:00+01:00'\nprint(next_schedule.isoformat())\n# Prints: '2021-01-02T00:00:00+01:00'\nprint(next_next_schedule.isoformat())\n```\nExample using python_dateutil:\n```python\nimport dateutil.tz\nfrom datetime import datetime\nfrom cron_converter import Cron\n\ntz = dateutil.tz.gettz('Asia/Tokyo')\nlocal_date = datetime(2021, 1, 1, tzinfo=tz)\ncron = Cron('0 0 * * *')\nschedule = cron.schedule(start_date=local_date)\nnext_schedule = schedule.next()\nnext_next_schedule = schedule.next()\n# Prints: '2021-01-01T00:00:00+09:00'\nprint(next_schedule.isoformat())\n# Prints: '2021-01-02T00:00:00+09:00'\nprint(next_next_schedule.isoformat())\n```\n\n## About Cron schedule times frequency\nIt's possible to compare the Cron object schedules frequency. Thanks [@zevaverbach](https://github.com/zevaverbach).\n```python\n# Hours\nCron('0 1 * * 1-5') == Cron('0 2 * * 1-5') # True\nCron('0 1,2,3 * * 1-5') > Cron('0 1,23 * * 1-5') # True\n# Minutes\nCron('* 1 * * 1-5') == Cron('0-59 1 * * 1-5') # True\nCron('1-30 1 * * 1-5') > Cron('1-29 1 * * 1-5') # True\n# Days\nCron('* 1 1 * 1-5') == Cron('0-59 1 2 * 1-5') # True\nCron('* 1 1,2 * 1-5') > Cron('* 1 6 * 1-5') # True\n# Month\nCron('* 1 1 11 1-5') == Cron('* 1 1 1 1-5') # True\nCron('* 1 6 * 1-5') > Cron('* 1 6 1 1-5') # True\n# WeekDay\nCron('* 1 1 11 *') == Cron('* 1 1 11 0-6') # True\nCron('* 1 6 * 1-5') > Cron('* 1 6 * 1-4') # True\n```\n\n## About seconds repeats\nCron-converter is NOT able to do second repetition crontabs form.\n\n## About datetime objects validation\nCron can also validate datetime objects (datetime and date).\n```python\nCron(\"* * 10 * *\").validate(datetime(2022, 1, 10, 1, 9)) # True\nCron(\"* * 12 * *\").validate(datetime(2022, 1, 10, 1, 9)) # False\n```\n\nA datetime object can also be validated with the `in` operator\n```python\ndatetime(2024, 3, 19, 15, 55) in Cron('*/5 9-17/2 * 1-3 1-5') # True\n```\n\n## Develop & Tests\n```bash\ngit clone https://github.com/Sonic0/cron-converter\ncd cron-converter\n...\npython -m unittest discover -s tests/unit\npython -m unittest discover -s tests/integration\n```\n\n## Project info\nThis repo is part of a projects group, called _Cron-Converter_.\nIts related repositories:\n\n- [local-crontab](https://github.com/Sonic0/local-crontab)\n- [local-crontab-ansible-filter](https://github.com/Sonic0/local-crontab-ansible-filter)\n- [local-crontab-serverless-infrastructure](https://github.com/Sonic0/local-crontab-serverless-infrastructure)\n- [local-crontab-web-converter](https://github.com/Sonic0/local-crontab-web-converter)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Cron string parser and scheduler for Python",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/Sonic0/cron-converter"
},
"split_keywords": [
"cron"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e717c3174a2cf713289e723c50b535c8d0eaf726d44fc428420b9830986f344c",
"md5": "29c5f97cb9897577a53407d32b127681",
"sha256": "fc2d055c691880b5ef3eb525de7a513287b9dd0ec00232300663ff5a3c66dd4a"
},
"downloads": -1,
"filename": "cron_converter-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29c5f97cb9897577a53407d32b127681",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13200,
"upload_time": "2024-03-24T21:49:36",
"upload_time_iso_8601": "2024-03-24T21:49:36.291040Z",
"url": "https://files.pythonhosted.org/packages/e7/17/c3174a2cf713289e723c50b535c8d0eaf726d44fc428420b9830986f344c/cron_converter-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "943eb6b6e09adaa6b5d1eb2c7d91df542b57f2131ed2df592f344da1a5085438",
"md5": "8e092b5336cebda4d67862b7d8002292",
"sha256": "169a5788d05a28627ab9dcb688ec39a395a40782142360518cb3ad43b025cee7"
},
"downloads": -1,
"filename": "cron-converter-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8e092b5336cebda4d67862b7d8002292",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13887,
"upload_time": "2024-03-24T21:49:37",
"upload_time_iso_8601": "2024-03-24T21:49:37.771473Z",
"url": "https://files.pythonhosted.org/packages/94/3e/b6b6e09adaa6b5d1eb2c7d91df542b57f2131ed2df592f344da1a5085438/cron-converter-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 21:49:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sonic0",
"github_project": "cron-converter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cron-converter"
}
JSON
