# Temporals
The goal of this library is to provide a minimalistic, out-of-the-box utility on top of the Python's
`datetime` in regards to working with time and date, or both, periods.
> :warning: As it currently stands (assume the latest release), the library has no out of the box support
> for "aware" datetime objects. All the calculations are done by the Python `datetime` library.
## Quickstart
### Installation
You can either download the latest package from this repository or via pip:
`pip install temporals`
### Periods
The library offers access to three different types of periods:
- **TimePeriod**
The `TimePeriod` class allows you to define a period using `datetime.time`, and as such, is limited
to just the 24 hours within a day.
- **DatePeriod**
The `DatePeriod` class allows you to define a period using `datetime.date` and work with any dates
within its bounds.
- **DatetimePeriod**
This is the most complete implementation of both periods above as it contains both a date, and a time,
defined using `datetime.datetime`.
### Documentation
In-depth documentation available on the Wiki page of the repository - https://github.com/dimitarOnGithub/temporals/wiki
### Examples
As mentioned above, you might find use for the different periods in different situations, let's look at
the following `TimePeriod` example:
```python
from datetime import time
from temporals import TimePeriod
workday = TimePeriod(start=time(8, 0), end=time(18, 0))
# Do you have an important call scheduled?
client_call = time(13, 0)
print(client_call in workday) # True
# Or maybe you have an appointment and you want to see if it overlaps with your work hours?
appointment = TimePeriod(start=time(17, 30), end=time(18, 15))
appointment.overlaps_with(workday) # True
# Let's see what's the overlap like, so you can plan accordingly
overlap = appointment.get_overlap(workday) # get_overlap returns a TimePeriod
print(overlap) # 17:30:00/18:00:00
```
---
Let's do something less day-to-day like, with this `DatePeriod`:
```python
from datetime import date
from temporals import DatePeriod
time_off = DatePeriod(start=date(2024, 8, 1), end=date(2024, 8, 14))
# All roads lead to Rome
italy_visit = DatePeriod(start=date(2024, 8, 3), end=date(2024, 8, 10))
# I hope you have a good... how long again?
print(italy_visit.duration) # P0Y0M1W0DT0H0M0S
# Wow, that sure is a mouthful, can we get it simplified?
print(italy_visit.duration.isoformat(fold=True)) # 'P1W'
```
---
Sometimes, we need both date and time to properly describe a period in time and this is the purpose
`DatetimePeriod` serves
```python
from datetime import datetime
from temporals import DatetimePeriod
takeoff = datetime(2024, 8, 2, 22, 11, 34) # 22:11:34, 2nd of Aug 2024
landing = datetime(2024, 8, 3, 4, 55, 3) # 04:55:03, 3rd of Aug 2024
flight = DatetimePeriod(start=takeoff, end=landing)
print(flight)
# 2024-08-02T22:11:34/2024-08-03T04:55:03
# This is a PITA to read, why not try something nicer
print(flight.duration.isoformat())
# PT6H43M29S
# "Stop. Enhance. Give me a hard copy right there."
pattern = "%Hh%Mm"
formatted_time = flight.duration.format(pattern)
sentence = f"The flight lasted around {formatted_time}"
print(sentence)
# The flight lasted around 6h43m
```
Raw data
{
"_id": null,
"home_page": null,
"name": "temporals",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "time, date, datetime, period, interval",
"author": null,
"author_email": "Dimitar Ivanov <dimitarxivanov@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a7/6c/12266b0b552c52659d8119b79d9103bcd5d030a67ce9d6530ec12acd1f45/temporals-0.1.5.tar.gz",
"platform": null,
"description": "# Temporals\n\nThe goal of this library is to provide a minimalistic, out-of-the-box utility on top of the Python's \n`datetime` in regards to working with time and date, or both, periods.\n\n> :warning: As it currently stands (assume the latest release), the library has no out of the box support\n> for \"aware\" datetime objects. All the calculations are done by the Python `datetime` library.\n\n## Quickstart\n\n### Installation\n\nYou can either download the latest package from this repository or via pip:\n\n`pip install temporals`\n\n### Periods\n\nThe library offers access to three different types of periods:\n\n- **TimePeriod**\n\n The `TimePeriod` class allows you to define a period using `datetime.time`, and as such, is limited\nto just the 24 hours within a day.\n\n- **DatePeriod**\n\n The `DatePeriod` class allows you to define a period using `datetime.date` and work with any dates\nwithin its bounds.\n\n- **DatetimePeriod**\n\n This is the most complete implementation of both periods above as it contains both a date, and a time, \ndefined using `datetime.datetime`.\n\n### Documentation\n\nIn-depth documentation available on the Wiki page of the repository - https://github.com/dimitarOnGithub/temporals/wiki\n\n### Examples\n\nAs mentioned above, you might find use for the different periods in different situations, let's look at\nthe following `TimePeriod` example:\n```python\nfrom datetime import time\nfrom temporals import TimePeriod\n\nworkday = TimePeriod(start=time(8, 0), end=time(18, 0))\n# Do you have an important call scheduled?\nclient_call = time(13, 0)\nprint(client_call in workday) # True\n\n# Or maybe you have an appointment and you want to see if it overlaps with your work hours?\nappointment = TimePeriod(start=time(17, 30), end=time(18, 15))\nappointment.overlaps_with(workday) # True\n\n# Let's see what's the overlap like, so you can plan accordingly\noverlap = appointment.get_overlap(workday) # get_overlap returns a TimePeriod\nprint(overlap) # 17:30:00/18:00:00\n```\n\n---\n\nLet's do something less day-to-day like, with this `DatePeriod`:\n```python\nfrom datetime import date\nfrom temporals import DatePeriod\n\ntime_off = DatePeriod(start=date(2024, 8, 1), end=date(2024, 8, 14))\n# All roads lead to Rome\nitaly_visit = DatePeriod(start=date(2024, 8, 3), end=date(2024, 8, 10))\n\n# I hope you have a good... how long again?\nprint(italy_visit.duration) # P0Y0M1W0DT0H0M0S\n# Wow, that sure is a mouthful, can we get it simplified?\nprint(italy_visit.duration.isoformat(fold=True)) # 'P1W'\n```\n\n---\n\nSometimes, we need both date and time to properly describe a period in time and this is the purpose\n`DatetimePeriod` serves\n```python\nfrom datetime import datetime\nfrom temporals import DatetimePeriod\n\ntakeoff = datetime(2024, 8, 2, 22, 11, 34) # 22:11:34, 2nd of Aug 2024\nlanding = datetime(2024, 8, 3, 4, 55, 3) # 04:55:03, 3rd of Aug 2024\n\nflight = DatetimePeriod(start=takeoff, end=landing)\nprint(flight) \n# 2024-08-02T22:11:34/2024-08-03T04:55:03\n\n# This is a PITA to read, why not try something nicer\nprint(flight.duration.isoformat())\n# PT6H43M29S\n\n# \"Stop. Enhance. Give me a hard copy right there.\"\npattern = \"%Hh%Mm\"\nformatted_time = flight.duration.format(pattern)\nsentence = f\"The flight lasted around {formatted_time}\"\nprint(sentence)\n# The flight lasted around 6h43m\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library providing time, date and datetime periods support",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/dimitarOnGithub/temporals/wiki",
"Homepage": "https://github.com/dimitarOnGithub/temporals",
"Issues": "https://github.com/dimitarOnGithub/temporals/issues"
},
"split_keywords": [
"time",
" date",
" datetime",
" period",
" interval"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa72f75da7b77b4195d5e3462f40025ce862f6f5eda21dbd2b070f76878a25f6",
"md5": "0b13c4462b060fe7269b3b65c7c4aa15",
"sha256": "ab0e2f5c8eebaa13a0c105e22e41cf67f6248794b3f3aa05cd1d548a8b88a87e"
},
"downloads": -1,
"filename": "temporals-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b13c4462b060fe7269b3b65c7c4aa15",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15806,
"upload_time": "2024-10-14T15:36:05",
"upload_time_iso_8601": "2024-10-14T15:36:05.381170Z",
"url": "https://files.pythonhosted.org/packages/fa/72/f75da7b77b4195d5e3462f40025ce862f6f5eda21dbd2b070f76878a25f6/temporals-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a76c12266b0b552c52659d8119b79d9103bcd5d030a67ce9d6530ec12acd1f45",
"md5": "c9c918ee6199ed9883a1204cfb7f96e9",
"sha256": "b6d45b3b270196f7f3f676a29e2997d2156dc9d7b61defb4c814476f19791cdd"
},
"downloads": -1,
"filename": "temporals-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "c9c918ee6199ed9883a1204cfb7f96e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21258,
"upload_time": "2024-10-14T15:36:06",
"upload_time_iso_8601": "2024-10-14T15:36:06.908375Z",
"url": "https://files.pythonhosted.org/packages/a7/6c/12266b0b552c52659d8119b79d9103bcd5d030a67ce9d6530ec12acd1f45/temporals-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 15:36:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dimitarOnGithub",
"github_project": "temporals",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
"==",
"8.2.2"
]
]
}
],
"lcname": "temporals"
}
JSON
