Skip to main content

tslite-OG

 _       _ _ _
| |_ ___| (_) |_ ___
| __/ __| | | __/ _ \
| |_\__ \ | | ||  __/
 \__|___/_|_|\__\___| v2.1.0
 a lightweight timeseries library

The original lightweight time-series library. Since 2009.

Small enough to understand. Flexible enough for real-world data.

tslite works with timestamp/value observations, whether they arrive regularly, contain gaps, or turn up out of order. It provides arithmetic, filtering, interpolation, moving windows, statistics, and SQLite storage without requiring a DataFrame or NumPy.

Background

I started tslite in 2009 to work with time series in an elegant, practical way. I've maintained and used it ever since, particularly for engineering and hydrological data. Real observations are messy: the goal is accurate calculations with explicit, useful ways to handle that mess.

The project remains tslite on GitHub and in Python. Its PyPI distribution is tslite-og—a distinct package name for the original library's modern continuation. It is still a single Python module, not a framework.

Installation

Requires Python 3.11 or newer.

pip install tslite-og
# Or:
uv add tslite-og
import tslite

NumPy is optional, needed only for the NumPy-based filters:

pip install 'tslite-og[numpy]'

Start with observations

from datetime import datetime
from tslite import timeseries

flow = timeseries([
    (datetime(2024, 1, 1, 2), 12),
    (datetime(2024, 1, 1, 0), 2),
    (datetime(2024, 1, 1, 1), 4),
])

# Observations are sorted; inserting an existing timestamp replaces its value.
print(flow.values())                  # [2.0, 4.0, 12.0]
print(flow.globalAverage()[1])        # 6.0
print(flow.runningTotal().values())   # [2.0, 6.0, 18.0]
print(flow.firstdifference().values())  # [2.0, 8.0]

Calculations return new series, so transformations can be chained:

adjusted = flow.mul(1.5).add(2)
high_flow = flow.cullBelow(3)  # Keep values greater than 3.

print(adjusted.values())   # [5.0, 8.0, 20.0]
print(high_flow.values())  # [4.0, 12.0]

Moving windows

Intervals accept strings such as "30m", "2h", or "1d6h", as well as datetime.timedelta objects. Moving averages weight observations equally and include both window endpoints.

print(flow.movingaverage("2h").values())        # [2.0, 3.0, 6.0]
print(flow.centerMovingAverage("2h").values())  # [3.0, 6.0, 8.0]

# Require complete windows instead of averaging available edge observations.
print(flow.movingaverage("2h", require_full_window=True).values())  # [6.0]

Make a grid and select matching data

grid = timeseries.createRegular(
    start=datetime(2024, 1, 1, 0),
    end=datetime(2024, 1, 1, 4),
    interval="2h",
)
selected = grid.cut(flow)
print(selected.values())  # [2.0, 12.0]

grid.cut(flow) keeps flow's values at exact grid timestamps. It doesn't invent missing observations. Use interpolation or filling when that's intended.

Compare messy data explicitly

from datetime import timedelta

shifted = flow.timeshift(timedelta(milliseconds=1))

assert flow != shifted                       # Exact timestamps and values.
assert flow.same_data(shifted)                # Compare values, ignoring timestamps.
assert flow.is_close(shifted, time_tolerance="0.001s")

is_close() accepts timestamp, absolute-value, and relative-value tolerances:

matches = flow.is_close(
    shifted,
    time_tolerance="1s",
    value_tolerance=0.001,
    relative_tolerance=0.0001,
)

Observations are compared in order; lengths must match. No hidden realignment or interpolation occurs.

Store observations in SQLite

import sqlite3

with sqlite3.connect("observations.sqlite3") as connection:
    flow.saveSQLITE3(connection, "flow")
    if flow.status != "OK":
        raise RuntimeError(flow.status)

    loader = timeseries()
    recent = loader.loadSQLITE3(
        connection, "flow",
        start_time=datetime(2024, 1, 1, 1),
    )
    if loader.status != "OK":
        raise RuntimeError(loader.status)

print(recent.values())  # [4.0, 12.0]

Saves insert new timestamps and update only changed values. Existing caller transactions remain under the caller's control. SQLite preserves timestamps as integer microseconds. Binary, TSV, and JSON helpers are also available.

Ready for more? Read the tslite manual for public methods, worked examples, time conventions, and storage. See the changelog when upgrading.

Development and documentation

uv sync --extra numpy
uv run pytest

Documentation is ordinary Markdown: this introduction and the manual. No site generator needed. The manual explains public methods with examples; source docstrings provide quick help inside Python.

Tests include executable README/manual examples, small numerical calculations, and read-only historical fixtures. Run all supported Python versions and verify locally built packages with:

uv run python scripts/verify_release.py

See the changelog for changes and migration details. Source: github.com/gunnarleffler/tslite.

License

Apache License 2.0.

Metadata

Release files for tslite-og 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tslite-og 2.1.0
File Size Uploaded Provenance Actions
tslite_og-2.1.0.tar.gz 1.1 MB Without provenance Details for tslite_og-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tslite-og 2.1.0
File Interpreter ABI Platform Actions
tslite_og-2.1.0-py3-none-any.whl Python 3 none any Details for tslite_og-2.1.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / tslite_og-2.1.0.tar.gz

Download URL tslite_og-2.1.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
640de9f51880875ce0ef2e7fcc68db441f2c11762713a1a124f1bf34b8482d17
BLAKE2b-256 checksum
How to use checksums
0436cbbec5fe6d806eaf839c1700d1226022e8a800f1c8208fad7bfcac6c695d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Release files / tslite_og-2.1.0-py3-none-any.whl

Download URL tslite_og-2.1.0-py3-none-any.whl
Size 28.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5ea97300a8498838e5dd27b3bf58b91b1b7438971041c2036cf907325078618
BLAKE2b-256 checksum
How to use checksums
b72d060a7d80ea3e853a3f46024b127b6c3577207f09959310fb1238ed79541b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Security for tslite-og 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page