# xchronos
An innovated periodic cron time utility using similar but extended expression with cron, and optimized algorithm implementation for large number of steps search (by calculation instead of looping and try);
Supports search with both point of datetime and period of datetime extended expression, e.g. nth week of month in a year and nth week of year;
Natively support and optimize for large number of steps use case, e.g. what whould next xth time point be; Implemention largely reduces the search time complexity by using calculation instead of looping and try each available time point;
Support period of time search, e.g. if a time point is between time A and time B;
## Install
- python >= 3.8
```bash
pip install xchronos
```
## xcron expression
### Difference
Different from traditional cron expression, it represent the datetime from year to seconds; it also have several addional time units you can use;
### Datetime Unit
There are 5 conventional cron used time units: month, day of month, day of week, hour, minutes and additional 4 time units: year, week of year, week of month, seconds; These units should be ordered from year to second when use;
### Calendar Mode
In favor of extending time expression with extra time units, there are 4 calendar modes as following enum or str representation:
```py
class CMode(str, Enum):
M = "m" # month between year and day: month of year mode
MW = "mw" # month and week between year and day: monthweek mode
D = "_" # nothing between year and day: day of year mode
W = "w" # week between year and day: week of year mode
```
### Outline
putting these together, the cron string should have the following outline for different mode:
CMode.M / "m": Year Month "Day of Month" Hour Minute Second
CMode.MW / "mw": Year Month "Week of Month" "Day of Week" Hour Minute Second
Cmode.D / "-": Year "Day of Year" Hour Minute Second
Cmode.W / "w": Year "Week of Year" "Day of Week" Hour Minute Second
- Second at end is optional and default to 0
### Pattern
0. space indicate the seperation of units, it should only appear in between units;
1. use 1 base number for unit in calendar and 0 base for time, simply put L before number to represent the last xth number, e.g. L1 for last 1, L5 for last 5;
- 0 indicate the first number always;
2. "*" wildcard to indicate every number in the units;
3. "-" connect two number to indicate a range, inclusive, if follow by "/number", it indicates every #number of number from start to end, notice that end may not appear in possible number set, the set follow the calculation of start + number*k;
4. "," seperation a list enum of numbers;
5. "; m|mw|-|w", choose one of the mode to represent, use ";" to seperate the mode string "m", "mw", "-", or "w" from the main pattern string;
- if you omit mode string here, you'll need to specify it in class loader later;
### Period Pattern
5. "..", In favor of expression a period of time, introduce .. as a new pattern, .. is short for 0..-1, you can specify or omit number on either side.
- Only .. pattern or a single number can apear after it, and a single number X will be translated into X..X;
- When this apears, it means the current and following units of time are seen as one unit block, and it apears in every periodic pattern described as the units before it. e.g. "2019 1,3,5 * 8..16 0..59 0; m" meaning 8:00:00 to 16:59:00 in every day in every Jan, March, May in year 2019;
6. Examples:
- "* 1,L1 8 *; -": every 0 second of every minutes of 8 o'clock in first and last day of every year;
- "2000 1 1 * */3 0 0; mw": every 3 hour of every day in Jan first month of 2000;
## Usage
### Chronos for time point
```py
from chronos import Chronos
cron = Chronos("* * * 1,3,5 * * ; m")
assert cron.prev(datetime(2003, 11, 10, 6, 0, 6)) == datetime(2003, 11, 10, 6, 0, 5)
assert cron.prev(datetime(2003, 11, 10, 6, 0, 6), 1) == datetime(2003, 11, 10, 6, 0, 5)
assert cron.prev(datetime(2003, 11, 10, 6, 0, 6), leap=1) == datetime(2003, 11, 10, 6, 0, 5)
assert cron.prev(datetime(2003, 11, 10, 6, 0, 6), leap=10) == datetime(2003, 11, 9, 5, 59, 50)
assert cron.next(datetime(2003, 11, 10, 5, 59, 59)) == datetime(2003, 11, 11, 1, 0, 0)
# If current datetime represented by the cron
cron.contains(datetime.now())
```
### Chronos for time period
```py
from chronos import ChronoPeriod
period = ChronoPeriod("* 1,3,5 * 3..5 0 0 0; mw")
assert period.contains(datetime(2003, 5, 16, 0, 0, 0))
```
* ChronoPeriod instance has start and end field, they are instances of Chronnos class; To calculate next start, simply access the field and call next method;
## Definitions
Date definitions agree with ISO standard:
week of year / Month: https://en.wikipedia.org/wiki/ISO_week_date
Raw data
{
"_id": null,
"home_page": "https://github.com/RobbieL-nlp/xchronos",
"name": "xchronos",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cron,chronos,period,time,date,datetime,cronos",
"author": "RobbieL-nlp",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/46/bc/98192a4439a8b3fd1ef04f68524780b32099a7ba9dd0e26029a46243b9de/xchronos-0.1.1.tar.gz",
"platform": null,
"description": "# xchronos\n\nAn innovated periodic cron time utility using similar but extended expression with cron, and optimized algorithm implementation for large number of steps search (by calculation instead of looping and try); \n\nSupports search with both point of datetime and period of datetime extended expression, e.g. nth week of month in a year and nth week of year;\n\nNatively support and optimize for large number of steps use case, e.g. what whould next xth time point be; Implemention largely reduces the search time complexity by using calculation instead of looping and try each available time point;\n\nSupport period of time search, e.g. if a time point is between time A and time B;\n\n\n## Install\n\n- python >= 3.8\n\n```bash\npip install xchronos\n```\n\n## xcron expression\n\n### Difference\n\nDifferent from traditional cron expression, it represent the datetime from year to seconds; it also have several addional time units you can use; \n\n### Datetime Unit\n\nThere are 5 conventional cron used time units: month, day of month, day of week, hour, minutes and additional 4 time units: year, week of year, week of month, seconds; These units should be ordered from year to second when use;\n\n### Calendar Mode \n\nIn favor of extending time expression with extra time units, there are 4 calendar modes as following enum or str representation:\n\n```py\n\nclass CMode(str, Enum):\n M = \"m\" # month between year and day: month of year mode\n MW = \"mw\" # month and week between year and day: monthweek mode\n D = \"_\" # nothing between year and day: day of year mode\n W = \"w\" # week between year and day: week of year mode\n\n```\n\n### Outline\n\nputting these together, the cron string should have the following outline for different mode:\n\nCMode.M / \"m\": Year Month \"Day of Month\" Hour Minute Second \n\nCMode.MW / \"mw\": Year Month \"Week of Month\" \"Day of Week\" Hour Minute Second\n\nCmode.D / \"-\": Year \"Day of Year\" Hour Minute Second\n\nCmode.W / \"w\": Year \"Week of Year\" \"Day of Week\" Hour Minute Second\n\n- Second at end is optional and default to 0\n\n### Pattern\n\n0. space indicate the seperation of units, it should only appear in between units; \n\n1. use 1 base number for unit in calendar and 0 base for time, simply put L before number to represent the last xth number, e.g. L1 for last 1, L5 for last 5; \n - 0 indicate the first number always;\n\n2. \"*\" wildcard to indicate every number in the units;\n\n3. \"-\" connect two number to indicate a range, inclusive, if follow by \"/number\", it indicates every #number of number from start to end, notice that end may not appear in possible number set, the set follow the calculation of start + number*k;\n\n4. \",\" seperation a list enum of numbers;\n\n5. \"; m|mw|-|w\", choose one of the mode to represent, use \";\" to seperate the mode string \"m\", \"mw\", \"-\", or \"w\" from the main pattern string;\n - if you omit mode string here, you'll need to specify it in class loader later;\n### Period Pattern\n\n5. \"..\", In favor of expression a period of time, introduce .. as a new pattern, .. is short for 0..-1, you can specify or omit number on either side.\n - Only .. pattern or a single number can apear after it, and a single number X will be translated into X..X;\n - When this apears, it means the current and following units of time are seen as one unit block, and it apears in every periodic pattern described as the units before it. e.g. \"2019 1,3,5 * 8..16 0..59 0; m\" meaning 8:00:00 to 16:59:00 in every day in every Jan, March, May in year 2019;\n\n6. Examples:\n - \"* 1,L1 8 *; -\": every 0 second of every minutes of 8 o'clock in first and last day of every year;\n - \"2000 1 1 * */3 0 0; mw\": every 3 hour of every day in Jan first month of 2000; \n## Usage\n\n### Chronos for time point\n\n```py\nfrom chronos import Chronos\n\ncron = Chronos(\"* * * 1,3,5 * * ; m\")\n\nassert cron.prev(datetime(2003, 11, 10, 6, 0, 6)) == datetime(2003, 11, 10, 6, 0, 5)\nassert cron.prev(datetime(2003, 11, 10, 6, 0, 6), 1) == datetime(2003, 11, 10, 6, 0, 5)\nassert cron.prev(datetime(2003, 11, 10, 6, 0, 6), leap=1) == datetime(2003, 11, 10, 6, 0, 5)\nassert cron.prev(datetime(2003, 11, 10, 6, 0, 6), leap=10) == datetime(2003, 11, 9, 5, 59, 50)\n\nassert cron.next(datetime(2003, 11, 10, 5, 59, 59)) == datetime(2003, 11, 11, 1, 0, 0)\n\n# If current datetime represented by the cron\ncron.contains(datetime.now())\n\n```\n\n\n### Chronos for time period\n\n```py\nfrom chronos import ChronoPeriod\n\nperiod = ChronoPeriod(\"* 1,3,5 * 3..5 0 0 0; mw\")\n\nassert period.contains(datetime(2003, 5, 16, 0, 0, 0))\n\n```\n\n* ChronoPeriod instance has start and end field, they are instances of Chronnos class; To calculate next start, simply access the field and call next method;\n\n\n## Definitions\n\nDate definitions agree with ISO standard:\n\nweek of year / Month: https://en.wikipedia.org/wiki/ISO_week_date\n\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "An innovated periodic cron time utility using similar but extended expression with cron, and optimized algorithm implementation for large number of steps search.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/RobbieL-nlp/xchronos"
},
"split_keywords": [
"cron",
"chronos",
"period",
"time",
"date",
"datetime",
"cronos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48f8b7195e5a89c5b72494453a4629f7a99bd39fe2e22605fedf72160d81ae67",
"md5": "50232dee4b5589b7f47847b54acc2c08",
"sha256": "6b81abf988907e1b449f8ad60375cf2e4cfe465c6691832ff7efc5d30dc7e9f0"
},
"downloads": -1,
"filename": "xchronos-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50232dee4b5589b7f47847b54acc2c08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 2989,
"upload_time": "2024-03-04T18:27:22",
"upload_time_iso_8601": "2024-03-04T18:27:22.011648Z",
"url": "https://files.pythonhosted.org/packages/48/f8/b7195e5a89c5b72494453a4629f7a99bd39fe2e22605fedf72160d81ae67/xchronos-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46bc98192a4439a8b3fd1ef04f68524780b32099a7ba9dd0e26029a46243b9de",
"md5": "03cb9795f58fe7ae6509da8ca8e7868c",
"sha256": "8d8bc5c9d95f33bbf2cada996b62d4047216e12316fb30f7c9e6fd9f35ed1739"
},
"downloads": -1,
"filename": "xchronos-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "03cb9795f58fe7ae6509da8ca8e7868c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3945,
"upload_time": "2024-03-04T18:27:23",
"upload_time_iso_8601": "2024-03-04T18:27:23.427033Z",
"url": "https://files.pythonhosted.org/packages/46/bc/98192a4439a8b3fd1ef04f68524780b32099a7ba9dd0e26029a46243b9de/xchronos-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-04 18:27:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RobbieL-nlp",
"github_project": "xchronos",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xchronos"
}
JSON
