# Chronomeleon
🚧 Still Work In Progress!
[](LICENSE)
Chronomeleon is a Python package that converts and maps date and time information from their representation in one system to another.
It's meant to be used in data migration projects.
## Rationale
While converting a datetime alone is possible with either Python builtin tools or libraries like `pendulum` and `arrow`,
things become more complicated when you have to convert time slices or ranges or when the source and target system interpret dates and times differently.
Think your migrating e.g., contracts from system A to system B.
In system A might have an API, a data dump or something else from where you can read,
that a contract starts at `2024-01-01` and ends at `2024-06-30`.
Now assume, the same contract in system B starts at `2023-12-31T23:00:00Z` and ends at `2024-06-30T21:59:59Z`.
For this little conversion, although simple, you have to consider a lot:
* Are date and times implicitly "meant" in any certain time zone? Here, system A seems to implicitly assume, everything as German local time, whereas system B uses explicit UTC offsets.
* What about the resolution? Although using dates only might be sufficient for the modeling the business logic, as soon as the resolution of system B is higher, you have to start interpreting stuff.
* What if there was a system C, which supported microseconds but only stored the date and time in a single integer?
* What about the end date (times)? It seems that system A uses the end date as inclusive (contract ends at the end of june), whereas system B uses it as exclusive (start of the followup contract == end of the previous contract).
Chronomeleon has two purposes:
1. It forces you to make assumptions explicit.
2. Once the assumptions are explicit, it helps you do the conversion.
The latter is no rocket science (and neither is any line of code in chronomeleon), but making assumptions explicit is crucial and that's why using it is beneficial.
When you're constantly wondering why other coders seem to randomly
* add or subtract a day, a second, a tick here and there
* pass around naive dates and datetimes and try to convert them to UTC or other timezones with no clear reason
then chronomeleon is for you.
Chronomeleon makes your code more readable and makes your assumption clear.
This allows you to spot errors in your or your teammates code more easily and explain why things are done the way they are.
## How to use it?
Install it from pypi:
```bash
pip install chronomeleon
```
Then, in your code: Make assumptions about the source and target system explicit.
To do so, chronomeleon provides you with so-called ChronoConfig objects.
Here's an advanced example, that shows the capabilities of Chronomeleon:
```python
from datetime import date, datetime, timedelta
import pytz
from chronomeleon import ChronoAssumption, MappingConfig, adapt_to_target
config = MappingConfig( # make assumptions explicit
source=ChronoAssumption(
implicit_timezone=pytz.timezone("Europe/Berlin"),
resolution=timedelta(days=1),
is_inclusive_end=True,
is_gastag_aware=False,
),
target=ChronoAssumption(resolution=timedelta(milliseconds=1), is_inclusive_end=True, is_gastag_aware=True),
is_end=True,
is_gas=True,
)
source_value = date(2021, 12, 31)
result = adapt_to_target(source_value, config) # do the mapping
assert result == datetime(2022, 1, 1, 4, 59, 59, microsecond=999000, tzinfo=pytz.utc)
```
## Setup for Local Development
Follow the instructions from our [template repository](https://github.com/Hochfrequenz/python_template_repository?tab=readme-ov-file#how-to-use-this-repository-on-your-machine).
tl;dr: `tox`.
## Contribute
You are very welcome to contribute to this template repository by opening a pull request against the main branch.
Raw data
{
"_id": null,
"home_page": null,
"name": "chronomeleon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "conversion, date, dateonly, exclusive, inclusive, migration, time",
"author": null,
"author_email": "Hochfrequenz Unternehmensberatung GmbH <info+github@hochfrequenz.de>",
"download_url": "https://files.pythonhosted.org/packages/f9/8d/a0d2dafa5d393822201504508fa3eaf2e926da1737d69d999bd81f5df7fa/chronomeleon-0.1.0.tar.gz",
"platform": null,
"description": "# Chronomeleon\n\ud83d\udea7 Still Work In Progress!\n\n[](LICENSE)\n\n\n\n\n\n\n\nChronomeleon is a Python package that converts and maps date and time information from their representation in one system to another.\nIt's meant to be used in data migration projects.\n\n## Rationale\nWhile converting a datetime alone is possible with either Python builtin tools or libraries like `pendulum` and `arrow`,\nthings become more complicated when you have to convert time slices or ranges or when the source and target system interpret dates and times differently.\n\nThink your migrating e.g., contracts from system A to system B.\nIn system A might have an API, a data dump or something else from where you can read,\nthat a contract starts at `2024-01-01` and ends at `2024-06-30`.\n\nNow assume, the same contract in system B starts at `2023-12-31T23:00:00Z` and ends at `2024-06-30T21:59:59Z`.\n\nFor this little conversion, although simple, you have to consider a lot:\n* Are date and times implicitly \"meant\" in any certain time zone? Here, system A seems to implicitly assume, everything as German local time, whereas system B uses explicit UTC offsets.\n* What about the resolution? Although using dates only might be sufficient for the modeling the business logic, as soon as the resolution of system B is higher, you have to start interpreting stuff.\n * What if there was a system C, which supported microseconds but only stored the date and time in a single integer?\n* What about the end date (times)? It seems that system A uses the end date as inclusive (contract ends at the end of june), whereas system B uses it as exclusive (start of the followup contract == end of the previous contract).\n\nChronomeleon has two purposes:\n1. It forces you to make assumptions explicit.\n2. Once the assumptions are explicit, it helps you do the conversion.\n\nThe latter is no rocket science (and neither is any line of code in chronomeleon), but making assumptions explicit is crucial and that's why using it is beneficial.\n\nWhen you're constantly wondering why other coders seem to randomly\n* add or subtract a day, a second, a tick here and there\n* pass around naive dates and datetimes and try to convert them to UTC or other timezones with no clear reason\n\nthen chronomeleon is for you.\n\nChronomeleon makes your code more readable and makes your assumption clear.\nThis allows you to spot errors in your or your teammates code more easily and explain why things are done the way they are.\n\n## How to use it?\nInstall it from pypi:\n```bash\npip install chronomeleon\n```\n\nThen, in your code: Make assumptions about the source and target system explicit.\nTo do so, chronomeleon provides you with so-called ChronoConfig objects.\n\nHere's an advanced example, that shows the capabilities of Chronomeleon:\n```python\nfrom datetime import date, datetime, timedelta\n\nimport pytz\n\nfrom chronomeleon import ChronoAssumption, MappingConfig, adapt_to_target\n\nconfig = MappingConfig( # make assumptions explicit\n source=ChronoAssumption(\n implicit_timezone=pytz.timezone(\"Europe/Berlin\"),\n resolution=timedelta(days=1),\n is_inclusive_end=True,\n is_gastag_aware=False,\n ),\n target=ChronoAssumption(resolution=timedelta(milliseconds=1), is_inclusive_end=True, is_gastag_aware=True),\n is_end=True,\n is_gas=True,\n)\nsource_value = date(2021, 12, 31)\nresult = adapt_to_target(source_value, config) # do the mapping\nassert result == datetime(2022, 1, 1, 4, 59, 59, microsecond=999000, tzinfo=pytz.utc)\n```\n\n\n## Setup for Local Development\nFollow the instructions from our [template repository](https://github.com/Hochfrequenz/python_template_repository?tab=readme-ov-file#how-to-use-this-repository-on-your-machine).\ntl;dr: `tox`.\n\n## Contribute\nYou are very welcome to contribute to this template repository by opening a pull request against the main branch.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python package to flexibly adapt start and end date(times) to your system background",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/Hochfrequenz/chronomeleon/releases",
"Homepage": "https://github.com/Hochfrequenz/chronomeleon"
},
"split_keywords": [
"conversion",
" date",
" dateonly",
" exclusive",
" inclusive",
" migration",
" time"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76fdace6b79257632625046c4cf96fa70af71c212c8516a4430f290de5e6570b",
"md5": "0638522bd384920ca8dc99504c356bad",
"sha256": "bd3374b2a42ecad6dc0ef667ba94b04683da402dc5abc6195923c457b70468ac"
},
"downloads": -1,
"filename": "chronomeleon-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0638522bd384920ca8dc99504c356bad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9123,
"upload_time": "2024-05-13T14:15:13",
"upload_time_iso_8601": "2024-05-13T14:15:13.504754Z",
"url": "https://files.pythonhosted.org/packages/76/fd/ace6b79257632625046c4cf96fa70af71c212c8516a4430f290de5e6570b/chronomeleon-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f98da0d2dafa5d393822201504508fa3eaf2e926da1737d69d999bd81f5df7fa",
"md5": "315fffe96b4a9f277b43609293566492",
"sha256": "482f3002bc4c5e20bb9c3eedf18ba53133b795a3cc392f0b5cfa3a18f8d60bcc"
},
"downloads": -1,
"filename": "chronomeleon-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "315fffe96b4a9f277b43609293566492",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15254,
"upload_time": "2024-05-13T14:15:15",
"upload_time_iso_8601": "2024-05-13T14:15:15.812847Z",
"url": "https://files.pythonhosted.org/packages/f9/8d/a0d2dafa5d393822201504508fa3eaf2e926da1737d69d999bd81f5df7fa/chronomeleon-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 14:15:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hochfrequenz",
"github_project": "chronomeleon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytz",
"specs": [
[
"==",
"2024.1"
]
]
}
],
"tox": true,
"lcname": "chronomeleon"
}
JSON
