whisper

1.1.10 verified Fri May 01 auth: no python

Whisper is a fixed-size round-robin database library for storing time-series data, originally part of Graphite. The current version is 1.1.10, with irregular releases tied to the Graphite project. It provides a simple, file-based storage format for numeric data at fixed intervals.

pip install whisper

Common errors

error ImportError: cannot import name 'WhisperDB' from 'whisper' ↓

cause The symbol `WhisperDB` may not exist in older versions (pre-1.0) or if installed via the wrong package.

fix

Ensure you have whisper>=1.0.0 installed (pip install --upgrade whisper) and use from whisper import WhisperDB.

error TypeError: an integer is required (got type float) ↓

cause Passing a floating-point timestamp instead of an integer.

fix

Cast to int: int(your_timestamp).

Warnings

gotcha Whisper uses fixed-size archives. If you specify too few retention points, old data is silently overwritten (round-robin behavior). There is no warning. ↓

fix Plan archive sizes carefully to avoid losing data unexpectedly.

gotcha Timestamps must be integers (Unix timestamps). Passing a float or datetime object will raise a TypeError or produce incorrect results. ↓

fix Always convert to int: `int(time.time())`.

deprecated The `whisper.py` script (command-line tool) is not actively maintained and may have bugs. Use programmatic API instead. ↓

fix Use Python API (e.g., `from whisper import ...`) instead of shelling out.

Imports

WhisperDB
wrong
```
from whisper.whisper import WhisperDB
```
correct
```
from whisper import WhisperDB
```
Whisper does not have submodules; all symbols are directly in the `whisper` package.
create
```
from whisper import create
```
No common wrong import for 'create'.
update
```
from whisper import update
```
No common wrong import for 'update'.

Quickstart

Creates a new whisper database, updates it with a data point, and fetches the data.

from whisper import create, update, fetch
import time

# Create a whisper database with 1 hour of 1-minute archives
path = '/tmp/test.wsp'
create(path, [(1, 60)])  # 1 second precision, 60 points

# Update with a value
now = int(time.time())
update(path, now, 42.0)

# Fetch data
(fetch_info, data) = fetch(path, now - 60, now)
print(data)