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
