Metadata-Version: 2.4
Name: chronoseq
Version: 0.4.0
Summary: Exact time axes and time-indexed streams for Python
Author: ChronoSeq contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/stpoular/chronoseq
Project-URL: Repository, https://github.com/stpoular/chronoseq
Project-URL: Issues, https://github.com/stpoular/chronoseq/issues
Project-URL: Changelog, https://github.com/stpoular/chronoseq/blob/main/CHANGELOG.md
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)

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 fractions import Fraction

from chronoseq import Rate, Stream, timestamp

frames = Stream.regular(
    start=timestamp(0),
    rate=Rate(30),
    values=[f"frame_{i:03d}" for i in range(300)],
)

# Rate(n, d) means n / d hertz, i.e. samples per second.
# For example, Rate(30000, 1001) is an exact 29.97 fps-style rate.
# Decimal rates can be represented exactly with Fraction.
rate_2856 = Rate(Fraction("28.56"))

frame = frames.nearest(timestamp("0.101"))

print(frame.index)
print(frame.time)
print(frame.value)
```

For irregular sampled data:

```python
from chronoseq import Rate, Stream, timestamp

speed = Stream.irregular(
    timestamps=[
        timestamp("0.000"),
        timestamp("0.047"),
        timestamp("0.101"),
        timestamp("0.153"),
    ],
    values=[10.0, 10.3, 10.8, 11.1],
)

sample = speed.nearest(timestamp("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
