chronoseq 0.3.0__tar.gz

chronoseq-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stergios Poularakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chronoseq-0.3.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include CHANGELOG.md
+recursive-include docs *.md
+prune benchmarks
+prune samples
+prune tests
+prune .github
+global-exclude __pycache__ *.py[cod] .DS_Store

chronoseq-0.3.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: chronoseq
+Version: 0.3.0
+Summary: Exact time axes and time-indexed streams for Python
+Author: ChronoSeq contributors
+License-Expression: MIT
+Keywords: time,streams,sampling,timestamps,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# ChronoSeq
+
+[![CI](https://github.com/stpoular/chronoseq/actions/workflows/ci.yml/badge.svg)](https://github.com/stpoular/chronoseq/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+[![Types](https://img.shields.io/pypi/types/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+
+ChronoSeq is a Python library for time-indexed streams of sampled data. It provides exact integer-nanosecond timestamps, rational sampling rates, regular and irregular time axes, nearest-sample lookup, and half-open time-window slicing.
+Data may be stored in memory, a file, a database, a video container, an external API, or any custom backend.
+
+ChronoSeq has no time-zone, calendar, or wall-clock semantics. Timestamps are
+exact integer nanosecond offsets on a user-defined timeline.
+
+## Installation
+
+```bash
+pip install chronoseq
+```
+
+## Core model
+
+ChronoSeq has three main concepts:
+
+- `TimeAxis`: converts between timestamps and integer sample indices.
+- `Reader`: reads values by integer sample index.
+- `Stream`: combines a `TimeAxis` and `Reader` into a time-queryable stream.
+
+The common constructors are concise:
+
+```python
+from chronoseq import Hz, Stream, seconds
+
+frames = Stream.regular(
+    start=seconds(0),
+    rate=Hz(30),
+    values=[f"frame_{i:03d}" for i in range(300)],
+)
+
+frame = frames.nearest(seconds("0.101"))
+
+print(frame.index)
+print(frame.time)
+print(frame.value)
+```
+
+For irregular sampled data:
+
+```python
+from chronoseq import Stream, seconds
+
+speed = Stream.irregular(
+    timestamps=[
+        seconds("0.000"),
+        seconds("0.047"),
+        seconds("0.101"),
+        seconds("0.153"),
+    ],
+    values=[10.0, 10.3, 10.8, 11.1],
+)
+
+sample = speed.nearest(seconds("0.100"))
+```
+
+## More documentation
+
+- `docs/semantics.md`: formal timestamp, lookup, window, and reader rules.
+- `docs/custom_readers.md`: custom backend and stream extension patterns.
+- `docs/performance.md`: complexity notes, batching guidance, and benchmark snapshots.
+- `samples/`: dependency-free usage patterns.
+- `benchmarks/`: local benchmark scripts for large regular and irregular axes.
+
+## Licence
+
+MIT

chronoseq-0.3.0/README.md

@@ -0,0 +1,74 @@
+# ChronoSeq
+
+[![CI](https://github.com/stpoular/chronoseq/actions/workflows/ci.yml/badge.svg)](https://github.com/stpoular/chronoseq/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+[![Types](https://img.shields.io/pypi/types/chronoseq.svg)](https://pypi.org/project/chronoseq/)
+
+ChronoSeq is a Python library for time-indexed streams of sampled data. It provides exact integer-nanosecond timestamps, rational sampling rates, regular and irregular time axes, nearest-sample lookup, and half-open time-window slicing.
+Data may be stored in memory, a file, a database, a video container, an external API, or any custom backend.
+
+ChronoSeq has no time-zone, calendar, or wall-clock semantics. Timestamps are
+exact integer nanosecond offsets on a user-defined timeline.
+
+## Installation
+
+```bash
+pip install chronoseq
+```
+
+## Core model
+
+ChronoSeq has three main concepts:
+
+- `TimeAxis`: converts between timestamps and integer sample indices.
+- `Reader`: reads values by integer sample index.
+- `Stream`: combines a `TimeAxis` and `Reader` into a time-queryable stream.
+
+The common constructors are concise:
+
+```python
+from chronoseq import Hz, Stream, seconds
+
+frames = Stream.regular(
+    start=seconds(0),
+    rate=Hz(30),
+    values=[f"frame_{i:03d}" for i in range(300)],
+)
+
+frame = frames.nearest(seconds("0.101"))
+
+print(frame.index)
+print(frame.time)
+print(frame.value)
+```
+
+For irregular sampled data:
+
+```python
+from chronoseq import Stream, seconds
+
+speed = Stream.irregular(
+    timestamps=[
+        seconds("0.000"),
+        seconds("0.047"),
+        seconds("0.101"),
+        seconds("0.153"),
+    ],
+    values=[10.0, 10.3, 10.8, 11.1],
+)
+
+sample = speed.nearest(seconds("0.100"))
+```
+
+## More documentation
+
+- `docs/semantics.md`: formal timestamp, lookup, window, and reader rules.
+- `docs/custom_readers.md`: custom backend and stream extension patterns.
+- `docs/performance.md`: complexity notes, batching guidance, and benchmark snapshots.
+- `samples/`: dependency-free usage patterns.
+- `benchmarks/`: local benchmark scripts for large regular and irregular axes.
+
+## Licence
+
+MIT

chronoseq-0.3.0/chronoseq/__init__.py

@@ -0,0 +1,25 @@
+from .axis import IrregularTimeAxis, RegularTimeAxis, TimeAxis
+from .reader import MemoryReader, Reader
+from .stream import Sample, Stream, Window
+from .time import Duration, Hz, Rate, TimeLike, Timestamp, micros, millis, nanos, seconds, timestamp
+
+__all__ = [
+    "Duration",
+    "Hz",
+    "IrregularTimeAxis",
+    "MemoryReader",
+    "Rate",
+    "Reader",
+    "RegularTimeAxis",
+    "Sample",
+    "Stream",
+    "TimeAxis",
+    "Timestamp",
+    "TimeLike",
+    "Window",
+    "micros",
+    "millis",
+    "nanos",
+    "seconds",
+    "timestamp",
+]

chronoseq-0.3.0/chronoseq/axis.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from fractions import Fraction
+from typing import cast
+
+from .time import (
+    Rate,
+    TimeLike,
+    Timestamp,
+    as_timestamp,
+    floor_fraction_to_int,
+    round_fraction_to_int,
+)
+
+
+class TimeAxis(ABC):
+    """Converts between timestamps and integer sample indices."""
+
+    @abstractmethod
+    def time_at(self, index: int) -> Timestamp:
+        raise NotImplementedError
+
+    @abstractmethod
+    def nearest_index(self, time: TimeLike, *, length: int | None = None) -> int:
+        raise NotImplementedError
+
+    @abstractmethod
+    def index_at_or_before(self, time: TimeLike, *, length: int | None = None) -> int:
+        """Return the index of the sample at or before ``time``.
+
+        If ``time`` is earlier than the first sample, return 0. If a bounded
+        ``length`` is provided and the axis is empty, raise ``IndexError``.
+        """
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def index_at_or_after(self, time: TimeLike, *, length: int | None = None) -> int:
+        """Return the index of the sample at or after ``time``.
+
+        If ``time`` is later than the last bounded sample, return the final
+        bounded index. If a bounded ``length`` is provided and the axis is
+        empty, raise ``IndexError``.
+        """
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def index_range(
+        self,
+        start: TimeLike,
+        end: TimeLike,
+        *,
+        length: int | None = None,
+    ) -> range:
+        """Return indices for a half-open time window: [start, end)."""
+
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class RegularTimeAxis(TimeAxis):
+    """A time axis with samples taken at a fixed rate."""
+
+    start: TimeLike
+    rate: Rate
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "start", as_timestamp(self.start))
+
+    def time_at(self, index: int) -> Timestamp:
+        if index < 0:
+            raise IndexError("index must be non-negative")
+
+        frac_ns = Fraction(
+            index * 1_000_000_000 * self.rate.denominator,
+            self.rate.numerator,
+        )
+        return Timestamp(self.start.ns + round_fraction_to_int(frac_ns))
+
+    def nearest_index(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        if length is not None and length <= 0:
+            raise IndexError("empty axis")
+
+        after = self._lower_bound(time, length=length)
+
+        if after == 0:
+            return 0
+        if length is not None and after >= length:
+            return length - 1
+
+        before = after - 1
+        before_time = self.time_at(before)
+        after_time = self.time_at(after)
+
+        if abs(before_time.ns - time.ns) <= abs(after_time.ns - time.ns):
+            return before
+        return after
+
+    def index_at_or_before(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        if length is not None and length <= 0:
+            raise IndexError("empty axis")
+
+        after = self._upper_bound(time, length=length)
+        return max(0, after - 1)
+
+    def index_at_or_after(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        if length is not None and length <= 0:
+            raise IndexError("empty axis")
+
+        index = self._lower_bound(time, length=length)
+        if length is not None and index >= length:
+            return length - 1
+        return index
+
+    def index_range(
+        self,
+        start: TimeLike,
+        end: TimeLike,
+        *,
+        length: int | None = None,
+    ) -> range:
+        """Return indices for a half-open time window: [start, end)."""
+
+        start = as_timestamp(start)
+        end = as_timestamp(end)
+        if length is not None and length <= 0:
+            return range(0, 0)
+        if end.ns <= start.ns:
+            return range(0, 0)
+
+        first = self._lower_bound(start, length=length)
+        last_exclusive = self._lower_bound(end, length=length)
+
+        if length is not None and first >= length:
+            return range(0, 0)
+
+        if last_exclusive <= first:
+            return range(0, 0)
+
+        return range(first, last_exclusive)
+
+    def _lower_bound(self, time: Timestamp, *, length: int | None = None) -> int:
+        """Return the first index whose rounded timestamp is >= time.
+
+        The search is performed over ``time_at(index)`` rather than the ideal
+        fractional index. This matters for fractional rates and for rates above
+        nanosecond resolution, where several adjacent samples can round to the
+        same integer-nanosecond timestamp.
+        """
+
+        if length is not None and length <= 0:
+            raise IndexError("empty axis")
+
+        if time.ns <= self.start.ns:
+            return 0
+
+        if length is not None:
+            lo = 0
+            hi = length
+        else:
+            delta_ns = time.ns - self.start.ns
+            frac_index = Fraction(
+                delta_ns * self.rate.numerator,
+                1_000_000_000 * self.rate.denominator,
+            )
+            hi = max(1, floor_fraction_to_int(frac_index) + 2)
+            while self.time_at(hi).ns < time.ns:
+                hi *= 2
+            lo = 0
+
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if self.time_at(mid).ns < time.ns:
+                lo = mid + 1
+            else:
+                hi = mid
+
+        return lo
+
+    def _upper_bound(self, time: Timestamp, *, length: int | None = None) -> int:
+        """Return the first index whose rounded timestamp is > time."""
+
+        if length is not None and length <= 0:
+            raise IndexError("empty axis")
+
+        if length is not None:
+            lo = 0
+            hi = length
+        else:
+            if time.ns < self.start.ns:
+                return 0
+
+            delta_ns = time.ns - self.start.ns
+            frac_index = Fraction(
+                delta_ns * self.rate.numerator,
+                1_000_000_000 * self.rate.denominator,
+            )
+            hi = max(1, floor_fraction_to_int(frac_index) + 2)
+            while self.time_at(hi).ns <= time.ns:
+                hi *= 2
+            lo = 0
+
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if self.time_at(mid).ns <= time.ns:
+                lo = mid + 1
+            else:
+                hi = mid
+
+        return lo
+
+
+@dataclass(frozen=True)
+class IrregularTimeAxis(TimeAxis):
+    """A time axis with explicitly timestamped samples."""
+
+    timestamps: Sequence[TimeLike]
+
+    def __post_init__(self) -> None:
+        timestamps = tuple(as_timestamp(t) for t in self.timestamps)
+        for earlier, later in zip(timestamps, timestamps[1:], strict=False):
+            if later.ns < earlier.ns:
+                raise ValueError("timestamps must be sorted in ascending order")
+        object.__setattr__(self, "timestamps", timestamps)
+
+    @property
+    def _timestamp_tuple(self) -> tuple[Timestamp, ...]:
+        return cast(tuple[Timestamp, ...], self.timestamps)
+
+    def __len__(self) -> int:
+        return len(self._timestamp_tuple)
+
+    def time_at(self, index: int) -> Timestamp:
+        timestamps = self._timestamp_tuple
+        if index < 0 or index >= len(timestamps):
+            raise IndexError(index)
+        return timestamps[index]
+
+    def nearest_index(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        timestamps = self._timestamp_tuple
+        n = len(timestamps) if length is None else min(length, len(timestamps))
+        if n <= 0:
+            raise IndexError("empty axis")
+
+        pos = _lower_bound(timestamps, time, stop=n)
+
+        if pos == 0:
+            return 0
+        if pos >= n:
+            return n - 1
+
+        before = pos - 1
+        after = pos
+        if abs(timestamps[before].ns - time.ns) <= abs(timestamps[after].ns - time.ns):
+            return before
+        return after
+
+    def index_at_or_before(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        timestamps = self._timestamp_tuple
+        n = len(timestamps) if length is None else min(length, len(timestamps))
+        if n <= 0:
+            raise IndexError("empty axis")
+        pos = _upper_bound(timestamps, time, stop=n)
+        return max(0, pos - 1)
+
+    def index_at_or_after(self, time: TimeLike, *, length: int | None = None) -> int:
+        time = as_timestamp(time)
+        timestamps = self._timestamp_tuple
+        n = len(timestamps) if length is None else min(length, len(timestamps))
+        if n <= 0:
+            raise IndexError("empty axis")
+        pos = _lower_bound(timestamps, time, stop=n)
+        return min(pos, n - 1)
+
+    def index_range(
+        self,
+        start: TimeLike,
+        end: TimeLike,
+        *,
+        length: int | None = None,
+    ) -> range:
+        start = as_timestamp(start)
+        end = as_timestamp(end)
+        timestamps = self._timestamp_tuple
+        n = len(timestamps) if length is None else min(length, len(timestamps))
+        if n <= 0 or end.ns <= start.ns:
+            return range(0, 0)
+        first = _lower_bound(timestamps, start, stop=n)
+        last_exclusive = _lower_bound(timestamps, end, stop=n)
+        return range(first, last_exclusive)
+
+
+def _lower_bound(
+    timestamps: Sequence[Timestamp],
+    target: Timestamp,
+    *,
+    stop: int | None = None,
+) -> int:
+    lo = 0
+    hi = len(timestamps) if stop is None else stop
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if timestamps[mid].ns < target.ns:
+            lo = mid + 1
+        else:
+            hi = mid
+    return lo
+
+
+def _upper_bound(
+    timestamps: Sequence[Timestamp],
+    target: Timestamp,
+    *,
+    stop: int | None = None,
+) -> int:
+    lo = 0
+    hi = len(timestamps) if stop is None else stop
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if timestamps[mid].ns <= target.ns:
+            lo = mid + 1
+        else:
+            hi = mid
+    return lo

chronoseq-0.3.0/chronoseq/reader.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Generic, Protocol, TypeVar
+
+T = TypeVar("T")
+
+
+class Reader(Protocol[T]):
+    """Reads values by integer sample index."""
+
+    def __len__(self) -> int: ...
+
+    def read(self, indices: Sequence[int]) -> list[T]: ...
+
+
+class MemoryReader(Generic[T]):
+    """Reader backed by an in-memory sequence of values."""
+
+    def __init__(self, values: Sequence[T]):
+        self.values = values
+
+    def __len__(self) -> int:
+        return len(self.values)
+
+    def read(self, indices: Sequence[int]) -> list[T]:
+        return [self.values[i] for i in indices]