| Name | timelineomat JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | Squeeze events into timelines and other timeline manipulations |
| upload_time | 2024-05-25 20:54:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
database
event
time
timelines
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TimelineOMat
This project allows to streamline events in timelines.
Streamlining is here to fill to adjust the event start and stop times so it fits into the gaps of the timeline and to emit an Exception if this is not possible.
The timeline should be filled with the events with higher priority first and then descend in priority.
## Installation
``` sh
pip install timelineomat
```
## Usage
There are 5 different functions which also exist as methods of the TimelineOMat class
- streamline_event_times: checks how to short the given event to fit into the timelines. Without a timeline the result can be used for sorting (see section later)
- streamline_event: uses streamline_event_times plus setters to update the event and returns event
- transform_events_to_times: transforms timelines to TimeRangeTuple for e.g. databases
- ordered_insert: insert an event in a timeline so it stays ordered. By default an offset is returned. It can be used in case of ascending inserts to improve the performance
- streamline_ordered_insert: combined functions of ordered_insert and streamline_event. Works efficient on arrays also in descending order direction
ordered_insert also takes the parameters direction and offset (direction can be set on TimelineOMat). This allows performant inserts and collision checks.
When ordered_insert is called with offset 0 or unset it is safe to call even when the insertion order is chaotic
The timeline must be ordered anyway for ordered_insert
There is a new argument occlusions which must be of type list. It receives the
occluded time ranges
``` python
from dataclasses import dataclass
from datetime import datetime as dt
from timelineomat import TimelineOMat, streamline_event_times, stream_line_event, TimeRangeTuple
@dataclass
class Event:
start: dt
stop: dt
timeline = [
Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),
Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))
]
new_event = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))
# one time methods
# get intermediate result of new times
streamline_event_times(new_event, timeline) == TimeRangeTuple(start=dt(2024, 1, 3), stop=dt(2024, 1, 4))
# update the event
timeline.append(streamline_event(new_event, timeline))
tm = TimelineOMat()
# use method instead
tm.streamline_event_times(Event(start=dt(2024, 1, 1), stop=dt(2024, 1, )), timeline) == TimeRangeTuple(start=dt(2024, 1, 4), stop=dt(2024, 1, 5))
# now integrate in django or whatever
from django.db.models import Q
q = Q()
# this is not optimized
for timetuple, ev in tm.transform_events_to_times(timeline):
# timetuple is actually a 2 element tuple
q |= Q(timepoint__range=timetuple) & ~Q(id=ev.id)
```
## Tricks to integrate in different datastructures
TimelineOMat supports out of the box all kind of dicts as well as objects. It determinates
if an object is a dict and uses otherwise getattr and setattr. It even supports timelines with mixed types.
The easiest way to integrate Events in TimelineOMat with different names than start and stop is to provide
the names for `start_extractor` and `stop_extractor`.
When providing strings the string names are mirrored to the arguments:
`start_setter` and `stop_setter`. No need to set them explicitly.
### Data types of start, stop
the output format is always datetime but the input is flexible. Datetimes are nearly passed through
(naive datetimes can get a timezone set, more info later)
Int as well as float are also supported. In this case datetime.fromtimestamp is used.
In case of strings fromisodatestring is used.
#### Optional fallback timezones
All of TimelineOMat, streamline_event_times and streamline_event support an argument:
fallback_timezone
If set the timezone is used in case a naive datetime is encountered (in case of int, float, the timezone is always set).
Supported are the regular timezones of python (timezone.utc or ZoneInfo).
### TimelineOMat one-time overwrites
Given the code
``` python
from dataclasses import dataclass
from datetime import datetime as dt
from timelineomat import TimelineOMat
@dataclass
class Event:
start: dt
stop: dt
timeline = [
Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),
Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))
]
new_event1 = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))
new_event2 = dict(start=dt(2024, 1, 1), end=dt(2024, 1, 5))
tm = TimelineOMat()
```
it is possible to extract the data with
``` python
def one_time_overwrite_end(ev):
if isinstance(ev, dict):
return ev["end"]
else:
return ev.stop
timeline.append(tm.streamline_event(new_event1, timeline))
#
timeline.append(Event(**tm.streamline_event_times(new_event2, timeline, stop_extractor=one_time_overwrite_end)._asdict()))
```
## Tricks to improve the performance:
### Using TimelineOMat
In case of the one time methods the extractors and setters are generated all the time when using string extractors or setters -> bad performance
Building an TimelineOMat is more efficient or alternatively provide functions for extractors and setters
### Only the last element (sorted timelines)
For handling unsorted timelines TimelineOMat iterates through all events all the time.
In case of an ordered timeline the performance can be improved by using only the last element:
``` python
from dataclasses import dataclass
from datetime import datetime as dt
from timelineomat import TimelineOMat
@dataclass
class Event:
start: dt
stop: dt
ordered_timeline = [
Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),
Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))
]
new_event = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))
# here we generate the setters and extractors only onetime
tm = TimelineOMat()
tm.streamline_event_times(new_event, ordered_timeline[-1:])
```
In case the inserts are not completely ordered there is a helper named ordered_insert. It returns and takes (optionally) an offset. As soon as a break in the monotonic ascending or descending is detected, the offset can be set to 0.
Note: position and offset are in ascending orders the same.
``` python
from dataclasses import dataclass
from datetime import datetime as dt
from timelineomat import TimelineOMat
@dataclass
class Event:
start: dt
stop: dt
ordered_timeline = [
Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),
Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))
]
new_event1 = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))
new_event2 = Event(start=dt(2023, 1, 1), stop=dt(2023, 1, 4))
new_event3 = Event(start=dt(2025, 1, 1), stop=dt(2025, 1, 4))
new_event4 = Event(start=dt(2025, 2, 1), stop=dt(2025, 2, 4))
# here we generate the setters and extractors only onetime
tm = TimelineOMat(direction="desc")
position, offset = tm.ordered_insert(
tm.streamline_event(
new_event1, ordered_timeline[:len(ordered_timeline)-1-offset]
),
ordered_timeline
)
position, offset = tm.streamlined_ordered_insert(new_event2, ordered_timeline, offset=offset)
# is stable
position = tm.streamlined_ordered_insert(new_event2, ordered_timeline, ordered_timeline, offset=offset).position
# here is a break in the monotic order and we get ascending inserts
offset = 0
# ascending is easier, so split streamlined_ordered_insert into their inner commands
# for descending we need to build a reverse window of the array
position, offset = tm.ordered_insert(tm.streamline_event(new_event3, ordered_timeline), ordered_timeline, offset=offset, direction="asc")
position, offset = tm.ordered_insert(tm.streamline_event(new_event4, ordered_timeline[-1:]), ordered_timeline, offset=offset, direction="asc")
```
## How to integrate in db systems
DB Systems like django support range queries, which receives two element tuples. TimelineOMat can convert the timelines into such tuples (TimeRangeTuple doubles as tuple) with transform_events_to_times.
The result is an iterator which returns tuples of (TimeRangeTuple, Event)
An example is in Usage
Note: since 0.7.0 the Event from which the TimeRangeTuple is extracted is provided as second element
## How to use for sorting
simple use the streamline_event_times(...) method of TimelineOMat without any timelines as key function. By using the TimelineOMat class parameters can be preinitialized
The resulting tuple can be sorted
``` python
tm = TimelineOMat()
timeline.sort(key=tm.streamline_event_times)
```
To compare only the start or stop timestamps
``` python
tm = TimelineOMat()
timeline.sort(key=tm.start_extractor)
```
Another usage of the key function would be together with heapq to implement some kind of merge sort
## Changes
0.7.0 Breaking Change: transform_events_to_times is now an iterator and returns the event as second element
0.6.0 add streamlined_ordered_insert
0.5.0 add occlusions argument
0.4.0 rename NoCallAllowed to NoCallAllowedError
0.3.0 rename NewTimesResult to TimeRangeTuple (the old name is still available)
Raw data
{
"_id": null,
"home_page": null,
"name": "timelineomat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "database, event, time, timelines",
"author": null,
"author_email": "Alexander Kaftan <devkral@web.de>",
"download_url": "https://files.pythonhosted.org/packages/b6/65/6007f51c129deba7c3d02c0d22e8154d82a6d221c7fde153ee264883de21/timelineomat-0.7.0.tar.gz",
"platform": null,
"description": "# TimelineOMat\n\nThis project allows to streamline events in timelines.\nStreamlining is here to fill to adjust the event start and stop times so it fits into the gaps of the timeline and to emit an Exception if this is not possible.\nThe timeline should be filled with the events with higher priority first and then descend in priority.\n\n\n## Installation\n``` sh\npip install timelineomat\n```\n\n## Usage\n\nThere are 5 different functions which also exist as methods of the TimelineOMat class\n\n- streamline_event_times: checks how to short the given event to fit into the timelines. Without a timeline the result can be used for sorting (see section later)\n- streamline_event: uses streamline_event_times plus setters to update the event and returns event\n- transform_events_to_times: transforms timelines to TimeRangeTuple for e.g. databases\n- ordered_insert: insert an event in a timeline so it stays ordered. By default an offset is returned. It can be used in case of ascending inserts to improve the performance\n- streamline_ordered_insert: combined functions of ordered_insert and streamline_event. Works efficient on arrays also in descending order direction\n\nordered_insert also takes the parameters direction and offset (direction can be set on TimelineOMat). This allows performant inserts and collision checks.\n\nWhen ordered_insert is called with offset 0 or unset it is safe to call even when the insertion order is chaotic\n\nThe timeline must be ordered anyway for ordered_insert\n\nThere is a new argument occlusions which must be of type list. It receives the \noccluded time ranges\n\n``` python\nfrom dataclasses import dataclass\nfrom datetime import datetime as dt\nfrom timelineomat import TimelineOMat, streamline_event_times, stream_line_event, TimeRangeTuple\n\n\n@dataclass\nclass Event:\n start: dt\n stop: dt\n\ntimeline = [\n Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),\n Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))\n]\nnew_event = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))\n# one time methods\n# get intermediate result of new times\nstreamline_event_times(new_event, timeline) == TimeRangeTuple(start=dt(2024, 1, 3), stop=dt(2024, 1, 4))\n# update the event\ntimeline.append(streamline_event(new_event, timeline))\n\ntm = TimelineOMat()\n# use method instead\ntm.streamline_event_times(Event(start=dt(2024, 1, 1), stop=dt(2024, 1, )), timeline) == TimeRangeTuple(start=dt(2024, 1, 4), stop=dt(2024, 1, 5))\n\n# now integrate in django or whatever\nfrom django.db.models import Q\n\nq = Q()\n# this is not optimized\nfor timetuple, ev in tm.transform_events_to_times(timeline):\n # timetuple is actually a 2 element tuple\n q |= Q(timepoint__range=timetuple) & ~Q(id=ev.id)\n\n```\n\n\n## Tricks to integrate in different datastructures\n\nTimelineOMat supports out of the box all kind of dicts as well as objects. It determinates\nif an object is a dict and uses otherwise getattr and setattr. It even supports timelines with mixed types.\n\nThe easiest way to integrate Events in TimelineOMat with different names than start and stop is to provide\nthe names for `start_extractor` and `stop_extractor`.\nWhen providing strings the string names are mirrored to the arguments:\n`start_setter` and `stop_setter`. No need to set them explicitly.\n\n### Data types of start, stop\n\nthe output format is always datetime but the input is flexible. Datetimes are nearly passed through\n(naive datetimes can get a timezone set, more info later)\n\nInt as well as float are also supported. In this case datetime.fromtimestamp is used.\n\nIn case of strings fromisodatestring is used.\n\n#### Optional fallback timezones\n\nAll of TimelineOMat, streamline_event_times and streamline_event support an argument:\nfallback_timezone\n\nIf set the timezone is used in case a naive datetime is encountered (in case of int, float, the timezone is always set).\n\nSupported are the regular timezones of python (timezone.utc or ZoneInfo).\n\n### TimelineOMat one-time overwrites\n\n\nGiven the code\n\n\n``` python\nfrom dataclasses import dataclass\nfrom datetime import datetime as dt\nfrom timelineomat import TimelineOMat\n\n\n@dataclass\nclass Event:\n start: dt\n stop: dt\n\n\ntimeline = [\n Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),\n Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))\n]\nnew_event1 = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))\nnew_event2 = dict(start=dt(2024, 1, 1), end=dt(2024, 1, 5))\n\ntm = TimelineOMat()\n```\n\nit is possible to extract the data with\n\n``` python\n\n\ndef one_time_overwrite_end(ev):\n if isinstance(ev, dict):\n return ev[\"end\"]\n else:\n return ev.stop\n\ntimeline.append(tm.streamline_event(new_event1, timeline))\n#\n\ntimeline.append(Event(**tm.streamline_event_times(new_event2, timeline, stop_extractor=one_time_overwrite_end)._asdict()))\n```\n\n\n## Tricks to improve the performance:\n\n### Using TimelineOMat\n In case of the one time methods the extractors and setters are generated all the time when using string extractors or setters -> bad performance\n\nBuilding an TimelineOMat is more efficient or alternatively provide functions for extractors and setters\n\n### Only the last element (sorted timelines)\n\nFor handling unsorted timelines TimelineOMat iterates through all events all the time.\nIn case of an ordered timeline the performance can be improved by using only the last element:\n\n\n``` python\nfrom dataclasses import dataclass\nfrom datetime import datetime as dt\nfrom timelineomat import TimelineOMat\n\n\n@dataclass\nclass Event:\n start: dt\n stop: dt\n\nordered_timeline = [\n Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),\n Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))\n]\nnew_event = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))\n# here we generate the setters and extractors only onetime\ntm = TimelineOMat()\ntm.streamline_event_times(new_event, ordered_timeline[-1:])\n\n```\n\nIn case the inserts are not completely ordered there is a helper named ordered_insert. It returns and takes (optionally) an offset. As soon as a break in the monotonic ascending or descending is detected, the offset can be set to 0.\n\nNote: position and offset are in ascending orders the same.\n\n\n``` python\nfrom dataclasses import dataclass\nfrom datetime import datetime as dt\nfrom timelineomat import TimelineOMat\n\n\n@dataclass\nclass Event:\n start: dt\n stop: dt\n\nordered_timeline = [\n Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 2)),\n Event(start=dt(2024, 1, 2), stop=dt(2024, 1, 3))\n]\nnew_event1 = Event(start=dt(2024, 1, 1), stop=dt(2024, 1, 4))\nnew_event2 = Event(start=dt(2023, 1, 1), stop=dt(2023, 1, 4))\nnew_event3 = Event(start=dt(2025, 1, 1), stop=dt(2025, 1, 4))\nnew_event4 = Event(start=dt(2025, 2, 1), stop=dt(2025, 2, 4))\n# here we generate the setters and extractors only onetime\ntm = TimelineOMat(direction=\"desc\")\nposition, offset = tm.ordered_insert(\n tm.streamline_event(\n new_event1, ordered_timeline[:len(ordered_timeline)-1-offset]\n ),\n ordered_timeline\n)\nposition, offset = tm.streamlined_ordered_insert(new_event2, ordered_timeline, offset=offset)\n# is stable\nposition = tm.streamlined_ordered_insert(new_event2, ordered_timeline, ordered_timeline, offset=offset).position\n# here is a break in the monotic order and we get ascending inserts\noffset = 0\n# ascending is easier, so split streamlined_ordered_insert into their inner commands\n# for descending we need to build a reverse window of the array\nposition, offset = tm.ordered_insert(tm.streamline_event(new_event3, ordered_timeline), ordered_timeline, offset=offset, direction=\"asc\")\nposition, offset = tm.ordered_insert(tm.streamline_event(new_event4, ordered_timeline[-1:]), ordered_timeline, offset=offset, direction=\"asc\")\n\n```\n\n\n## How to integrate in db systems\n\nDB Systems like django support range queries, which receives two element tuples. TimelineOMat can convert the timelines into such tuples (TimeRangeTuple doubles as tuple) with transform_events_to_times.\n\nThe result is an iterator which returns tuples of (TimeRangeTuple, Event)\n\nAn example is in Usage\n\nNote: since 0.7.0 the Event from which the TimeRangeTuple is extracted is provided as second element\n\n\n## How to use for sorting\n\nsimple use the streamline_event_times(...) method of TimelineOMat without any timelines as key function. By using the TimelineOMat class parameters can be preinitialized\n\nThe resulting tuple can be sorted\n\n``` python\n\ntm = TimelineOMat()\ntimeline.sort(key=tm.streamline_event_times)\n\n```\n\nTo compare only the start or stop timestamps\n\n``` python\n\ntm = TimelineOMat()\ntimeline.sort(key=tm.start_extractor)\n\n```\n\nAnother usage of the key function would be together with heapq to implement some kind of merge sort\n\n## Changes\n\n0.7.0 Breaking Change: transform_events_to_times is now an iterator and returns the event as second element\n0.6.0 add streamlined_ordered_insert\n0.5.0 add occlusions argument\n0.4.0 rename NoCallAllowed to NoCallAllowedError\n0.3.0 rename NewTimesResult to TimeRangeTuple (the old name is still available)\n",
"bugtrack_url": null,
"license": null,
"summary": "Squeeze events into timelines and other timeline manipulations",
"version": "0.7.0",
"project_urls": null,
"split_keywords": [
"database",
" event",
" time",
" timelines"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1492fb036448df9dd1077f2a47aadfbda1081b9af099a273bca5a6e0a7ecab5c",
"md5": "c3ca232211b16f8bb667b3e6ed87c415",
"sha256": "bdb0defe10d944aa848dfb2351e3068b8e44c1cdfdece363965eb54b39508725"
},
"downloads": -1,
"filename": "timelineomat-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3ca232211b16f8bb667b3e6ed87c415",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7668,
"upload_time": "2024-05-25T20:54:31",
"upload_time_iso_8601": "2024-05-25T20:54:31.581768Z",
"url": "https://files.pythonhosted.org/packages/14/92/fb036448df9dd1077f2a47aadfbda1081b9af099a273bca5a6e0a7ecab5c/timelineomat-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b6656007f51c129deba7c3d02c0d22e8154d82a6d221c7fde153ee264883de21",
"md5": "3445084b557c664f7d96b4b8f12e99f3",
"sha256": "c4b2ffa97440ac346367cdff91fa2ad290bebac22a28ac8e5b17f1d67f357ddf"
},
"downloads": -1,
"filename": "timelineomat-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3445084b557c664f7d96b4b8f12e99f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9466,
"upload_time": "2024-05-25T20:54:30",
"upload_time_iso_8601": "2024-05-25T20:54:30.203642Z",
"url": "https://files.pythonhosted.org/packages/b6/65/6007f51c129deba7c3d02c0d22e8154d82a6d221c7fde153ee264883de21/timelineomat-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-25 20:54:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "timelineomat"
}
