# 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:

```bash
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.
