chronoseq 0.3.0__py3-none-any.whl

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/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/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]

chronoseq/stream.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence, Sized
+from dataclasses import dataclass
+from itertools import islice
+from typing import Generic, TypeVar
+
+from .axis import IrregularTimeAxis, RegularTimeAxis, TimeAxis
+from .reader import MemoryReader, Reader
+from .time import Duration, Rate, TimeLike, Timestamp, as_timestamp
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Sample(Generic[T]):
+    index: int
+    time: Timestamp
+    value: T
+
+
+class Stream(Generic[T]):
+    """Combines a TimeAxis and Reader into a time-queryable stream."""
+
+    def __init__(self, axis: TimeAxis, reader: Reader[T]):
+        axis_length = len(axis) if isinstance(axis, Sized) else None
+        reader_length = len(reader)
+        if axis_length is not None and axis_length != reader_length:
+            raise ValueError(
+                "finite axis and reader must have the same length "
+                f"({axis_length} != {reader_length})"
+            )
+        self.axis = axis
+        self.reader = reader
+
+    @classmethod
+    def regular(
+        cls,
+        *,
+        start: TimeLike,
+        rate: Rate,
+        values: Sequence[T],
+    ) -> Stream[T]:
+        return cls(
+            axis=RegularTimeAxis(start=start, rate=rate),
+            reader=MemoryReader(values),
+        )
+
+    @classmethod
+    def irregular(
+        cls,
+        *,
+        timestamps: Sequence[TimeLike],
+        values: Sequence[T],
+    ) -> Stream[T]:
+        if len(timestamps) != len(values):
+            raise ValueError("timestamps and values must have the same length")
+        return cls(
+            axis=IrregularTimeAxis(timestamps),
+            reader=MemoryReader(values),
+        )
+
+    def __len__(self) -> int:
+        return len(self.reader)
+
+    @property
+    def first_time(self) -> Timestamp:
+        """Timestamp of the first sample.
+
+        Raises ``IndexError`` for an empty stream.
+        """
+
+        if len(self) == 0:
+            raise IndexError("empty stream")
+        return self.time_at(0)
+
+    @property
+    def last_time(self) -> Timestamp:
+        """Timestamp of the last sample.
+
+        This is the final sample's timestamp, not an exclusive stop time.
+        Raises ``IndexError`` for an empty stream.
+        """
+
+        if len(self) == 0:
+            raise IndexError("empty stream")
+        return self.time_at(len(self) - 1)
+
+    @property
+    def duration(self) -> Duration:
+        """Duration between the first and last sample timestamps."""
+
+        if len(self) <= 1:
+            return Duration(0)
+        return self.last_time - self.first_time
+
+    def time_at(self, index: int) -> Timestamp:
+        self._check_index(index)
+        return self.axis.time_at(index)
+
+    def read(self, indices: Sequence[int]) -> list[T]:
+        """Read values for indices, preserving order.
+
+        Custom readers must return exactly one value per requested index. A
+        mismatch is treated as a reader contract violation and raises
+        ``ValueError`` rather than silently dropping or inventing samples.
+        """
+
+        index_list = list(indices)
+        for index in index_list:
+            self._check_index(index)
+        values = self.reader.read(index_list)
+        if len(values) != len(index_list):
+            raise ValueError(
+                "reader returned "
+                f"{len(values)} value(s) for {len(index_list)} requested index/indices"
+            )
+        return values
+
+    def read_one(self, index: int) -> T:
+        return self.read([index])[0]
+
+    def sample_at(self, index: int) -> Sample[T]:
+        return Sample(index=index, time=self.time_at(index), value=self.read_one(index))
+
+    def samples_at(self, indices: Sequence[int]) -> list[Sample[T]]:
+        index_list = list(indices)
+        values = self.read(index_list)
+        return [
+            Sample(index=index, time=self.axis.time_at(index), value=value)
+            for index, value in zip(index_list, values, strict=True)
+        ]
+
+    def nearest_index(self, time: TimeLike) -> int:
+        return self.axis.nearest_index(time, length=len(self))
+
+    def nearest(self, time: TimeLike) -> Sample[T]:
+        return self.sample_at(self.nearest_index(time))
+
+    def at_or_before_index(self, time: TimeLike) -> int:
+        return self.axis.index_at_or_before(time, length=len(self))
+
+    def at_or_before(self, time: TimeLike) -> Sample[T]:
+        return self.sample_at(self.at_or_before_index(time))
+
+    def at_or_after_index(self, time: TimeLike) -> int:
+        return self.axis.index_at_or_after(time, length=len(self))
+
+    def at_or_after(self, time: TimeLike) -> Sample[T]:
+        return self.sample_at(self.at_or_after_index(time))
+
+    def window(self, start: TimeLike, end: TimeLike) -> Window[T]:
+        indices = self.axis.index_range(as_timestamp(start), as_timestamp(end), length=len(self))
+        return Window(stream=self, indices=indices)
+
+    def window_before(self, end: TimeLike, duration: Duration) -> Window[T]:
+        end_ts = as_timestamp(end)
+        return self.window(start=end_ts - duration, end=end_ts)
+
+    def _check_index(self, index: int) -> None:
+        if index < 0 or index >= len(self):
+            raise IndexError(index)
+
+
+@dataclass(frozen=True)
+class Window(Generic[T]):
+    """Lazy view over a stream and a set of indices."""
+
+    stream: Stream[T]
+    indices: range | Sequence[int]
+
+    def __len__(self) -> int:
+        return len(self.indices)
+
+    def values(self) -> list[T]:
+        return self.stream.read(self.indices)
+
+    def samples(self) -> list[Sample[T]]:
+        return self.stream.samples_at(self.indices)
+
+    def batches(self, size: int) -> Iterator[list[Sample[T]]]:
+        """Yield samples from this window in bounded batches.
+
+        ``size`` must be a positive integer. Each yielded batch preserves index
+        order and contains at most ``size`` samples. The final batch may be
+        shorter. Empty windows yield no batches. This method consumes the
+        window indices incrementally and does not materialise the full index set
+        before yielding the first batch.
+        """
+
+        if isinstance(size, bool) or not isinstance(size, int):
+            raise TypeError("batch size must be an integer")
+        if size <= 0:
+            raise ValueError("batch size must be positive")
+
+        iterator = iter(self.indices)
+        while True:
+            batch_indices = list(islice(iterator, size))
+            if not batch_indices:
+                return
+            yield self.stream.samples_at(batch_indices)
+
+    def __iter__(self) -> Iterator[Sample[T]]:
+        """Yield samples one at a time without materialising the whole window."""
+
+        for index in self.indices:
+            yield self.stream.sample_at(index)

chronoseq/time.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from fractions import Fraction
+from functools import total_ordering
+from typing import overload
+
+NumberLike = int | float | str | Decimal
+
+_NS_PER_SECOND = Decimal("1000000000")
+_NS_PER_MILLISECOND = Decimal("1000000")
+_NS_PER_MICROSECOND = Decimal("1000")
+
+
+@dataclass(frozen=True, order=True)
+class Duration:
+    """An exact duration represented as integer nanoseconds."""
+
+    ns: int
+
+    def __post_init__(self) -> None:
+        if isinstance(self.ns, bool) or not isinstance(self.ns, int):
+            raise TypeError("Duration nanoseconds must be an integer")
+
+    def __add__(self, other: Duration) -> Duration:
+        """Add two durations."""
+
+        if not isinstance(other, Duration):
+            raise TypeError("Duration can only be added to another Duration")
+        return Duration(self.ns + other.ns)
+
+    def __sub__(self, other: Duration) -> Duration:
+        """Subtract one duration from another."""
+
+        if not isinstance(other, Duration):
+            raise TypeError("Duration can only subtract another Duration")
+        return Duration(self.ns - other.ns)
+
+    def __neg__(self) -> Duration:
+        """Return the negated duration."""
+
+        return Duration(-self.ns)
+
+    def __mul__(self, factor: int) -> Duration:
+        """Multiply this duration by an integer factor."""
+
+        if isinstance(factor, bool) or not isinstance(factor, int):
+            raise TypeError("Duration can only be multiplied by an integer")
+        return Duration(self.ns * factor)
+
+    def __rmul__(self, factor: int) -> Duration:
+        """Multiply this duration by an integer factor."""
+
+        return self * factor
+
+    def __floordiv__(self, divisor: int) -> Duration:
+        """Divide this duration by an integer, rounding down to nanoseconds."""
+
+        if isinstance(divisor, bool) or not isinstance(divisor, int):
+            raise TypeError("Duration can only be floor-divided by an integer")
+        return Duration(self.ns // divisor)
+
+    def to_seconds(self) -> Decimal:
+        """Return this duration as Decimal seconds."""
+
+        return Decimal(self.ns) / _NS_PER_SECOND
+
+
+@dataclass(frozen=True, order=True)
+class Timestamp:
+    """An exact timestamp represented as integer nanoseconds."""
+
+    ns: int
+
+    def __post_init__(self) -> None:
+        if isinstance(self.ns, bool) or not isinstance(self.ns, int):
+            raise TypeError("Timestamp nanoseconds must be an integer")
+
+    def __add__(self, duration: Duration) -> Timestamp:
+        """Offset this timestamp by a duration."""
+
+        if not isinstance(duration, Duration):
+            raise TypeError("Timestamp can only be offset by a Duration")
+        return Timestamp(self.ns + duration.ns)
+
+    @overload
+    def __sub__(self, other: Duration) -> Timestamp: ...
+
+    @overload
+    def __sub__(self, other: Timestamp) -> Duration: ...
+
+    def __sub__(self, other: Duration | Timestamp) -> Duration | Timestamp:
+        """Subtract a duration or another timestamp.
+
+        ``timestamp - duration`` returns a ``Timestamp``.
+        ``timestamp - timestamp`` returns a ``Duration``.
+        """
+
+        if isinstance(other, Timestamp):
+            return Duration(self.ns - other.ns)
+        if isinstance(other, Duration):
+            return Timestamp(self.ns - other.ns)
+        raise TypeError("Timestamp can only subtract a Timestamp or Duration")
+
+    def to_seconds(self) -> Decimal:
+        """Return this timestamp as Decimal seconds."""
+
+        return Decimal(self.ns) / _NS_PER_SECOND
+
+
+TimeLike = Duration | Timestamp
+
+
+def _to_decimal(value: NumberLike) -> Decimal:
+    if isinstance(value, bool):
+        raise TypeError("boolean values are not valid time values")
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError) as exc:
+        raise ValueError(f"time value is not finite: {value!r}") from exc
+    if not result.is_finite():
+        raise ValueError(f"time value is not finite: {value!r}")
+    return result
+
+
+def _exact_scaled_int(value: NumberLike, scale: Decimal, unit: str) -> int:
+    scaled = _to_decimal(value) * scale
+    if scaled != scaled.to_integral_value():
+        raise ValueError(f"{unit} value is not exactly representable in nanoseconds: {value!r}")
+    return int(scaled)
+
+
+def nanos(value: NumberLike) -> Duration:
+    """Create a duration in nanoseconds.
+
+    Values must be integral nanoseconds. Fractional nanosecond inputs raise
+    ``ValueError`` rather than being silently truncated.
+    """
+
+    return Duration(_exact_scaled_int(value, Decimal(1), "nanoseconds"))
+
+
+def micros(value: NumberLike) -> Duration:
+    """Create a duration in microseconds.
+
+    Values must be exactly representable as integer nanoseconds.
+    """
+
+    return Duration(_exact_scaled_int(value, _NS_PER_MICROSECOND, "microseconds"))
+
+
+def millis(value: NumberLike) -> Duration:
+    """Create a duration in milliseconds.
+
+    Values must be exactly representable as integer nanoseconds.
+    """
+
+    return Duration(_exact_scaled_int(value, _NS_PER_MILLISECOND, "milliseconds"))
+
+
+def seconds(value: NumberLike) -> Duration:
+    """Create a duration in seconds.
+
+    Values must be exactly representable as integer nanoseconds.
+    """
+
+    return Duration(_exact_scaled_int(value, _NS_PER_SECOND, "seconds"))
+
+
+def timestamp(value: NumberLike, *, unit: str = "s") -> Timestamp:
+    """Create a timestamp.
+
+    The default unit is seconds. Supported units are "s", "ms", "us", and "ns".
+    Values must be exactly representable as integer nanoseconds.
+    """
+
+    if unit == "s":
+        return Timestamp(seconds(value).ns)
+    if unit == "ms":
+        return Timestamp(millis(value).ns)
+    if unit == "us":
+        return Timestamp(micros(value).ns)
+    if unit == "ns":
+        return Timestamp(nanos(value).ns)
+    raise ValueError(f"unsupported timestamp unit: {unit!r}")
+
+
+def as_timestamp(value: TimeLike) -> Timestamp:
+    """Interpret a Duration as a timestamp relative to zero."""
+
+    if isinstance(value, Timestamp):
+        return value
+    if isinstance(value, Duration):
+        return Timestamp(value.ns)
+    raise TypeError("expected a Timestamp or Duration")
+
+
+def as_duration(value: TimeLike) -> Duration:
+    """Interpret a Timestamp's raw nanoseconds as a duration."""
+
+    if isinstance(value, Duration):
+        return value
+    if isinstance(value, Timestamp):
+        return Duration(value.ns)
+    raise TypeError("expected a Timestamp or Duration")
+
+
+@total_ordering
+class Rate:
+    """Samples per second, stored exactly as a reduced ``Fraction``."""
+
+    __slots__ = ("_fraction",)
+
+    _fraction: Fraction
+
+    def __init__(self, numerator: int | Fraction, denominator: int = 1):
+        if isinstance(numerator, bool) or isinstance(denominator, bool):
+            raise TypeError("Rate values must be integers or Fractions, not booleans")
+        if denominator == 0:
+            raise ValueError("Rate denominator must be non-zero")
+        value = Fraction(numerator, denominator)
+        if value <= 0:
+            raise ValueError("Rate must be positive")
+        object.__setattr__(self, "_fraction", value)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if hasattr(self, "_fraction"):
+            raise AttributeError("Rate is immutable")
+        object.__setattr__(self, name, value)
+
+    @property
+    def fraction(self) -> Fraction:
+        """Return this rate as a reduced ``fractions.Fraction``."""
+
+        return self._fraction
+
+    @property
+    def numerator(self) -> int:
+        """Numerator of the reduced samples-per-second fraction."""
+
+        return self._fraction.numerator
+
+    @property
+    def denominator(self) -> int:
+        """Denominator of the reduced samples-per-second fraction."""
+
+        return self._fraction.denominator
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Rate):
+            return NotImplemented
+        return self.fraction == other.fraction
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Rate):
+            return NotImplemented
+        return self.fraction < other.fraction
+
+    def __hash__(self) -> int:
+        return hash(self.fraction)
+
+    def __repr__(self) -> str:
+        if self.denominator == 1:
+            return f"Rate({self.numerator})"
+        return f"Rate({self.numerator}, {self.denominator})"
+
+
+def Hz(numerator: int | Fraction, denominator: int = 1) -> Rate:
+    """Create an exact sampling rate in Hz."""
+
+    return Rate(numerator, denominator)
+
+
+def round_fraction_to_int(value: Fraction) -> int:
+    """Round a Fraction to the nearest integer, with halves away from zero."""
+
+    if value >= 0:
+        return int(value + Fraction(1, 2))
+    return int(value - Fraction(1, 2))
+
+
+def floor_fraction_to_int(value: Fraction) -> int:
+    """Return floor(value) for a Fraction."""
+
+    return value.numerator // value.denominator
+
+
+def ceil_fraction_to_int(value: Fraction) -> int:
+    """Return ceil(value) for a Fraction."""
+
+    return -((-value.numerator) // value.denominator)

chronoseq-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+chronoseq/__init__.py,sha256=G9klVhhYuH5BeBZcfT9RMfT3lm4nWkz77smP2p7nMZ8,547
+chronoseq/axis.py,sha256=eyzea0sa9rR-wM5o-kmFLfrJK1hnUEzIEVd1u8Px3x0,10150
+chronoseq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronoseq/reader.py,sha256=WXXbXRvgLtyF0bkJsOKtoRJuhq8R7eeyJabO849Z6Jg,646
+chronoseq/stream.py,sha256=GPqkFskJ_1wjPIdKXRWCJYMGtc23oMKF99_szXCql1E,6775
+chronoseq/time.py,sha256=WYQmODOGuCvw-XfShI4kBptIy3ou8bY51p9T2m5WzEM,9156
+chronoseq-0.3.0.dist-info/licenses/LICENSE,sha256=mRU2blkYDi7tJto3gWY9raxHr29RqlvxGTdLCilHkUI,1076
+chronoseq-0.3.0.dist-info/METADATA,sha256=sF3u0hHVenbl-FyQd14pgELn9sFuHelViobL9H6ofTA,3177
+chronoseq-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+chronoseq-0.3.0.dist-info/top_level.txt,sha256=PaSbwZzg2XtlXrTO6voHULHQrQEghE2k5icbxSRb6O0,10
+chronoseq-0.3.0.dist-info/RECORD,,

chronoseq-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chronoseq-0.3.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+chronoseq