KlineTimestamp

KlineTimestamp is a Python library designed to accurately and efficiently handle timestamps within discrete time intervals (klines or candlesticks), commonly used in financial time series and market analysis.

It provides a clean, immutable, timezone-aware API that makes reasoning about candle boundaries extremely intuitive.

Repository:
https://github.com/nand0san/KlineTimestamp

---

Features

• Canonical open/close computation
  Automatically snap any timestamp (ms) to the correct candle open/close.

• Timezone-aware conversions
  Built-in support for pytz with proper DST handling.

• Clean datetime integration
  Convert directly to datetime.datetime or pandas.Timestamp.

• Immutable API
  Every transformation returns a new instance (with_timezone, with_interval, addition/subtraction with timedelta).

• Navigation between candles
  Use next() and prev() to move through consecutive klines.

• Strict comparison semantics
  Candle identity depends only on (open, interval); timezone affects display only.

• Guaranteed total ordering
  Timestamps are comparable via lexicographic (open, tick_ms) ordering.

• Intervals that match Binance
  All fixed-duration Binance intervals included (minutes/hours/days/weeks).

---

Installation

pip install kline_timestamp

Requires Python 3.9+.

---

Dependencies

• pandas>=2.3.3,<3.0
• pytz>=2025.2

These are declared automatically in the installed package.

---

Usage

Creating an Instance

from kline_timestamp import KlineTimestamp

kt = KlineTimestamp(
    timestamp_ms=1633036800000,
    interval="1h",
    tzinfo="Europe/Madrid"
)

---

Opening and Closing Values

print(kt.open)   # candle open, epoch ms (UTC)
print(kt.close)  # candle close, epoch ms (UTC)
print(kt.tick_ms)  # duration of the interval in milliseconds

---

Conversions

To datetime

dt = kt.to_datetime()
print(dt)

To pandas.Timestamp

ts = kt.to_pandas_timestamp()
print(ts)

Both respect the instance’s tzinfo.

---

Changing Timezone

Instances are immutable; a new one is created:

kt_utc = kt.with_timezone("UTC")
print(kt_utc.to_datetime())

---

Changing Interval

kt_15m = kt.with_interval("15m")
print(kt_15m.open, kt_15m.close)

---

Navigating Between Klines

next_kt = kt.next()
prev_kt = kt.prev()

print(next_kt.to_datetime())
print(prev_kt.to_datetime())

---

Arithmetic with timedelta

from datetime import timedelta

kt_plus = kt + timedelta(hours=1)
kt_minus = kt - timedelta(hours=1)

To compute differences between two klines:

delta = kt - kt_other
print(delta)  # returns a timedelta

---

Comparisons

kt == kt_other
kt < kt_other
kt > kt_other

Comparison is defined as:

1. First by open (UTC ms),
2. Then by tick_ms (interval length).

Timezone is ignored for equality and ordering.

---

Supported Intervals

These intervals match the fixed-duration Binance intervals:

Interval	Duration
1m	1 minute
3m	3 minutes
5m	5 minutes
15m	15 minutes
30m	30 minutes
1h	1 hour
2h	2 hours
4h	4 hours
6h	6 hours
8h	8 hours
12h	12 hours
1d	1 day
3d	3 days
1w	1 week

These are guaranteed to have constant duration, which is required for a consistent Kline API.

---

Full Example

from kline_timestamp import KlineTimestamp
from datetime import timedelta

kt = KlineTimestamp(1633036800000, "1h", "Europe/Madrid")

print("Open:", kt.open)
print("Close:", kt.close)

print("Datetime:", kt.to_datetime())
print("Pandas:", kt.to_pandas_timestamp())

kt_utc = kt.with_timezone("UTC")
print("UTC:", kt_utc.to_datetime())

kt_plus = kt + timedelta(hours=1)
print("After +1h:", kt_plus.to_datetime())

print("Next:", kt.next().to_datetime())
print("Prev:", kt.prev().to_datetime())

kt_other = KlineTimestamp(1633033200000, "1h", "UTC")
print("Comparison:", kt > kt_other)
print("Time delta:", kt - kt_other)

---

License

MIT License. See the LICENSE file for details.

---

Contributing

Pull requests are welcome. Open an issue or send a PR at:

https://github.com/nand0san/KlineTimestamp

---

Acknowledgments

• Inspired by practical needs in quantitative financial analysis.
• Uses the excellent pytz and pandas libraries for timezone and datetime handling.