kline-timestamp 0.2.0
KlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals (klines/candlesticks), commonly used in financial data analysis.
Requires Python: >=3.9


# 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

```bash
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

```python
from kline_timestamp import KlineTimestamp

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

---

## Opening and Closing Values

```python
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`

```python
dt = kt.to_datetime()
print(dt)
```

### To `pandas.Timestamp`

```python
ts = kt.to_pandas_timestamp()
print(ts)
```

Both respect the instance’s `tzinfo`.

---

## Changing Timezone

Instances are immutable; a new one is created:

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

---

## Changing Interval

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

---

## Navigating Between Klines

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

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

---

## Arithmetic with `timedelta`

```python
from datetime import timedelta

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

To compute differences between two klines:

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

---

## Comparisons

```python
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

```python
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](LICENSE) file for details.

---

## Contributing

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

[https://github.com/nand0san/KlineTimestamp](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.