# regta-period
**Library to make moment-independent periods in python.
It's designed especially for [Regta Framework](https://github.com/SKY-ALIN/regta),
but with an ability to use it independently.**
[](https://github.com/SKY-ALIN/regta-period)
[](https://codecov.io/gh/SKY-ALIN/regta-period)
[](https://pypi.org/project/regta-period/)
[](https://github.com/SKY-ALIN/regta-period/blob/main/LICENSE)
## Moment-Independence Idea Explanation
This term in this context means that relying on this approach we can get the time to time
points regardless of the points in which we are.
```
|-----------------|
t1 t2 moment
--------|--------|--------|--------> time
|--------|
```
Whereas with the standard intervals like `datetime.timedelta`, we get an unnecessary offset:
```
|-----------------|
t1 t2 moment
--------|--------|--------|--------|--------> time
|-----------------|
```
For example, it is important in the context of the job scheduler, because when the
scheduler is redeployed or restarted, you can get an unnecessary time shift or
unnecessary execution of the job.
## Math Explanation Of Moment-Independence
### Regular Offset
Regular offset is the same as python's `timedelta` shift e.g. once per $n_1$ days,
$n_2$ hours, $n_3$ minutes, $n_4$ seconds, but with the moment-independence idea.
Essentially, it works as a remainder of the time division from the Unix epoch.
Let $t_{unix}$ be the moment of the Unix epoch, a moment that we can get a grip on.
$t$ is the current moment. Then, the time since epoch is:
$$\ \Delta t = t - t_{unix} $$
Let $T$ be our regular period. Thus, to calculate time until the next moment we must subtract
from our period the remainder of the division by the period. Final function to calculate
time until the next moment since current looks following:
$$\ f(t) = T - ( \Delta t \mod T ) = T - ( ( t - t_{unix} ) \mod T ) $$
### Time Offset
Time offset is stating the exact time e.g. at 9 pm, at 12 am, at 16:30, etc.
It works as a shift of the starting point in the exact time and time zone:
$$\ t_{unix} + \Delta t_{time} + \Delta t_{tz} $$
Note that it's not possible to combine exact time and short regular intervals such as
hours, minutes, and seconds.
### Time Windows
Time window is a static time frame in which the result should be included e.g. every Monday, every June, etc.
A window may be from $t_{min}$ to $t_{max}$, then function result must be included in this interval:
$$ t + f(t) \in [t_{min}, t_{max}] $$
If the expression above is true, it means that the result is included in the time window, and the result is correct.
If don't, we calculate the result from the maximum and calculate the next time window until we find a match:
$$ t + f(t) \notin [t_{min_n}, t_{max_n}] \longrightarrow f(t_{max_n}); [t_{min_{n+1}}, t_{max_{n+1}}] $$
## Installation
Install using `pip install regta-period` or `poetry add regta-period`
If you use python < 3.9, then also install backports: `pip install "backports.zoneinfo[tzdata]"`
## Examples
There are two ways to create periods: old school style and hipster style.
```python
from datetime import datetime
from zoneinfo import ZoneInfo
from regta_period import Period
# Hipster style
p = Period().every(3).days.at("17:00").by("Europe/Moscow")
# Old school style
p = Period(days=3, time="17:00", timezone=ZoneInfo("Europe/Moscow"))
# <Period: regular_offset=259200.0s, time_offset=61200s, timezone=Europe/Moscow>
# Every 3 days at 5 pm by Moscow time
t = datetime.now(tz=ZoneInfo("Europe/Moscow"))
next_moment: datetime = p.get_next(t) # f(t) + t
```
You also may combine a few periods to a single object with the same interface:
```python
from datetime import datetime
from regta_period import Period, PeriodAggregation, Weekdays
# Hipster style
p = Period().on.weekdays.at("18:00") | Period().on.weekends.at("21:00")
# You also may replace `|` with `.OR` to write shorter and more human-readable code
p = Period().on.weekdays.at("18:00").OR.on.weekends.at("21:00")
# Old school style
p = PeriodAggregation(
Period(
weekdays=[Weekdays.MONDAY, Weekdays.TUESDAY, Weekdays.WEDNESDAY, Weekdays.THURSDAY, Weekdays.FRIDAY],
time="18:00",
),
Period(
weekdays=[Weekdays.SATURDAY, Weekdays.SUNDAY],
time="21:00",
),
)
# All of the above will the same result:
# <PeriodAggregation: <Period: regular_offset=86400.0s, time_offset=64800s, weekdays=Tuesday,Monday,Thursday,Wednesday,Friday> OR <Period: regular_offset=86400.0s, time_offset=75600s, weekdays=Sunday,Saturday>>
# At 6 pm on weekdays (Monday-Friday) and at 9 pm on weekends (Saturday-Sunday)
t = datetime.now()
timedelta_to_the_next_moment = p.get_interval(t) # f(t)
```
---
Full documentation and reference are available at
[regta-period.alinsky.tech](https://regta-period.alinsky.tech)
Raw data
{
"_id": null,
"home_page": "https://regta-period.alinsky.tech",
"name": "regta-period",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.2,<4.0",
"maintainer_email": "",
"keywords": "time,intervals,periods,regta",
"author": "Vladimir Alinsky",
"author_email": "Vladimir@Alinsky.tech",
"download_url": "https://files.pythonhosted.org/packages/09/36/c7b9b845a6ddd5a3169d8cc71254197c4236fe8369937cd09ad7b91b107c/regta-period-0.2.0.tar.gz",
"platform": null,
"description": "# regta-period\n\n**Library to make moment-independent periods in python.\nIt's designed especially for [Regta Framework](https://github.com/SKY-ALIN/regta), \nbut with an ability to use it independently.**\n\n[](https://github.com/SKY-ALIN/regta-period)\n\n\n[](https://codecov.io/gh/SKY-ALIN/regta-period)\n[](https://pypi.org/project/regta-period/)\n[](https://github.com/SKY-ALIN/regta-period/blob/main/LICENSE)\n\n## Moment-Independence Idea Explanation\n\nThis term in this context means that relying on this approach we can get the time to time \npoints regardless of the points in which we are.\n```\n |-----------------|\n t1 t2 moment\n--------|--------|--------|--------> time\n |--------|\n```\n\nWhereas with the standard intervals like `datetime.timedelta`, we get an unnecessary offset:\n```\n |-----------------|\n t1 t2 moment\n--------|--------|--------|--------|--------> time\n |-----------------|\n```\n\nFor example, it is important in the context of the job scheduler, because when the\nscheduler is redeployed or restarted, you can get an unnecessary time shift or\nunnecessary execution of the job.\n\n## Math Explanation Of Moment-Independence\n\n### Regular Offset\n\nRegular offset is the same as python's `timedelta` shift e.g. once per $n_1$ days,\n$n_2$ hours, $n_3$ minutes, $n_4$ seconds, but with the moment-independence idea.\n\nEssentially, it works as a remainder of the time division from the Unix epoch.\nLet $t_{unix}$ be the moment of the Unix epoch, a moment that we can get a grip on.\n$t$ is the current moment. Then, the time since epoch is:\n\n$$\\ \\Delta t = t - t_{unix} $$\n\nLet $T$ be our regular period. Thus, to calculate time until the next moment we must subtract\nfrom our period the remainder of the division by the period. Final function to calculate\ntime until the next moment since current looks following:\n\n$$\\ f(t) = T - ( \\Delta t \\mod T ) = T - ( ( t - t_{unix} ) \\mod T ) $$\n\n### Time Offset\n\nTime offset is stating the exact time e.g. at 9 pm, at 12 am, at 16:30, etc.\nIt works as a shift of the starting point in the exact time and time zone:\n\n$$\\ t_{unix} + \\Delta t_{time} + \\Delta t_{tz} $$\n\nNote that it's not possible to combine exact time and short regular intervals such as\nhours, minutes, and seconds.\n\n### Time Windows\n\nTime window is a static time frame in which the result should be included e.g. every Monday, every June, etc. \nA window may be from $t_{min}$ to $t_{max}$, then function result must be included in this interval:\n\n$$ t + f(t) \\in [t_{min}, t_{max}] $$\n\nIf the expression above is true, it means that the result is included in the time window, and the result is correct. \nIf don't, we calculate the result from the maximum and calculate the next time window until we find a match:\n\n$$ t + f(t) \\notin [t_{min_n}, t_{max_n}] \\longrightarrow f(t_{max_n}); [t_{min_{n+1}}, t_{max_{n+1}}] $$\n\n## Installation\n\nInstall using `pip install regta-period` or `poetry add regta-period`\n\nIf you use python < 3.9, then also install backports: `pip install \"backports.zoneinfo[tzdata]\"`\n\n## Examples\n\nThere are two ways to create periods: old school style and hipster style.\n\n```python\nfrom datetime import datetime\nfrom zoneinfo import ZoneInfo\nfrom regta_period import Period\n\n# Hipster style\np = Period().every(3).days.at(\"17:00\").by(\"Europe/Moscow\")\n\n# Old school style\np = Period(days=3, time=\"17:00\", timezone=ZoneInfo(\"Europe/Moscow\"))\n\n# <Period: regular_offset=259200.0s, time_offset=61200s, timezone=Europe/Moscow>\n# Every 3 days at 5 pm by Moscow time\n\nt = datetime.now(tz=ZoneInfo(\"Europe/Moscow\"))\nnext_moment: datetime = p.get_next(t) # f(t) + t\n```\n\nYou also may combine a few periods to a single object with the same interface:\n\n```python\nfrom datetime import datetime\nfrom regta_period import Period, PeriodAggregation, Weekdays\n\n# Hipster style\np = Period().on.weekdays.at(\"18:00\") | Period().on.weekends.at(\"21:00\")\n# You also may replace `|` with `.OR` to write shorter and more human-readable code\np = Period().on.weekdays.at(\"18:00\").OR.on.weekends.at(\"21:00\")\n\n# Old school style\np = PeriodAggregation(\n Period(\n weekdays=[Weekdays.MONDAY, Weekdays.TUESDAY, Weekdays.WEDNESDAY, Weekdays.THURSDAY, Weekdays.FRIDAY],\n time=\"18:00\",\n ),\n Period(\n weekdays=[Weekdays.SATURDAY, Weekdays.SUNDAY],\n time=\"21:00\",\n ),\n)\n\n# All of the above will the same result:\n# <PeriodAggregation: <Period: regular_offset=86400.0s, time_offset=64800s, weekdays=Tuesday,Monday,Thursday,Wednesday,Friday> OR <Period: regular_offset=86400.0s, time_offset=75600s, weekdays=Sunday,Saturday>>\n# At 6 pm on weekdays (Monday-Friday) and at 9 pm on weekends (Saturday-Sunday)\n\nt = datetime.now()\ntimedelta_to_the_next_moment = p.get_interval(t) # f(t)\n```\n\n---\n\nFull documentation and reference are available at \n[regta-period.alinsky.tech](https://regta-period.alinsky.tech)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Moment-independent periods",
"version": "0.2.0",
"split_keywords": [
"time",
"intervals",
"periods",
"regta"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "61bc16dce9c142069b92d879590fce36",
"sha256": "b827a2ce01e7d80506d3bcb0286f3d8f6114b6e67312c23a1f6d756de6474640"
},
"downloads": -1,
"filename": "regta_period-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61bc16dce9c142069b92d879590fce36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.2,<4.0",
"size": 8879,
"upload_time": "2022-12-28T14:22:36",
"upload_time_iso_8601": "2022-12-28T14:22:36.207544Z",
"url": "https://files.pythonhosted.org/packages/1e/9d/8853439d84a3880f4b54b6f07fa1d7cfdd642f63672ec73ef6a8fae363be/regta_period-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "cc2ed0eac9579bcbde802f818c6559f0",
"sha256": "a32c6296ba839420ea4066af3c76f15ebae7831c7a01ddf4d946f32b428fc367"
},
"downloads": -1,
"filename": "regta-period-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cc2ed0eac9579bcbde802f818c6559f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.2,<4.0",
"size": 8462,
"upload_time": "2022-12-28T14:22:33",
"upload_time_iso_8601": "2022-12-28T14:22:33.694490Z",
"url": "https://files.pythonhosted.org/packages/09/36/c7b9b845a6ddd5a3169d8cc71254197c4236fe8369937cd09ad7b91b107c/regta-period-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-28 14:22:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "regta-period"
}
JSON