eventweave 0.2.0

Weave multiple streams of intervals into combinations

eventweave

Eventweave is a lightweight Python utility that groups overlapping events into chronological combinations. It is useful for temporal reasoning and event sourcing, allowing you to analyze and visualize the relationships between events that occur simultaneously.

Features

• Accepts any iterable of events with user-defined start and end times
• Yields sets of events that are simultaneously active at some point in time
• Handles edge cases for back-to-back, non-overlapping intervals
• Runs in O(n log n) time and O(n) space

Installation

This project is self-contained with no dependencies beyond the Python standard library.

You can install it using pip:

python -m pip install eventweave

Supported for Python 3.13 and above.

Example Usage

Define your events and a key function:

>>> from eventweave import interweave
>>>
>>> events = [
...     ("A", (1, 4)),
...     ("B", (2, 5)),
...     ("C", (5, 6)),
... ]
>>>
>>> def key(event):
...     return event[1]

Use interweave to iterate over overlapping combinations:

>>> result = list(interweave(events, key))
>>> expected = [
...     {('A', (1, 4))},
...     {('A', (1, 4)), ('B', (2, 5))},
...     {('B', (2, 5))},
...     {('C', (5, 6))},
... ]
>>> assert result == expected

Clarification of Overlapping Events

If one event ends at time T and another begins at time T, they are not considered overlapping. The model assumes the starting event ends just after T to preserve strict separation of events that merely touch.

This handling of edge cases can lead to surprising results in certain situations. For example, if a long-running event spans two shorter events - where the first ends exactly when the second starts - an additional combination may currently be produced that contains only the long-running event. This behavior may change in future versions.

Currently, instantaneous events - where the start and end times are the same - are not supported. Support will be added once their semantics are clearly defined.