AlgoTradeKit 0.7.1__tar.gz → 0.7.2__tar.gz

{algotradekit-0.7.1 → algotradekit-0.7.2}/CHANGELOG.md

@@ -7,6 +7,58 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.7.2] — 2026-06-20
+
+### Added
+
+#### `data` module
+- **`Normalizer`** — new class to ingest non-standard OHLCV CSV files and
+  convert them to the AlgoTradeKit standard format.  Features:
+  - Auto-detects whether timestamps are in **Unix seconds** (`< 10^10`) or
+    **milliseconds** (`≥ 10^10`) and converts to ms automatically.
+  - Fills missing optional columns (`close_time`, `quote_volume`, `trades`,
+    `taker_buy_base`, `taker_buy_quote`) with `None`; `volume` defaults to `0`.
+  - Date-range filtering via `start` / `end` attributes before returning data
+    (integers are also auto-detected as seconds or ms).
+  - Three usage modes: `normalize()` → DataFrame, `save()` → CSV path,
+    `normalize_and_save()` → `(DataFrame, path)`.
+  - `Normalizer` is now exported from `AlgoTradeKit.data`.
+
+#### `indicator` module
+- **`ATR`** — Average True Range using Wilder's RMA smoothing (`alpha = 1 / period`,
+  `min_periods = period`).  Matches TradingView `ta.atr()` output.
+  Exposes `atr` and `tr` properties and result-dict keys.
+  Default period: **14**.  Exported from `AlgoTradeKit.indicator`.
+- **`Ichimoku.span_a_raw`** and **`Ichimoku.span_b_raw`** — two new properties
+  (and `result` dict keys) exposing the **unshifted** Senkou Span A and B values
+  at each bar (i.e. `(tenkan + kijun) / 2` and the Span B donchian mid *before*
+  the displacement shift is applied).  These are required for strategy entry/exit
+  logic where the current cloud position matters, not the displayed future cloud.
+  Fully backward-compatible — no existing keys or properties were changed.
+
+#### `visual` module
+- **`Chart.set_data(candle_range=...)`** — new optional `candle_range` dict
+  parameter filters which candles are rendered.  Five modes:
+  - `{"start": ..., "end": ...}` — inclusive datetime range (either key optional)
+  - `{"start": ...}` — from date to the last available candle
+  - `{"end": ...}` — from the first candle to date
+  - `{"last_n": N}` — last N candles
+  - `{"first_n": N}` — first N candles
+
+  `start` / `end` accept `"YYYY/MM/DD"`, `"YYYY-MM-DD"` strings, `datetime`
+  objects, Unix-second `int`, or Unix-millisecond `int`.
+- **`Chart.from_csv(candle_range=...)`** — `candle_range` forwarded from the
+  factory class method.
+
+### Tests
+- `tests/test_data_normalizer.py` — 25+ unit tests for `Normalizer` covering
+  timestamp detection, date filtering, schema completeness, save/load round-trip,
+  and error paths.
+- `tests/test_indicator.py` — extended with `TestATR` (15 tests) and
+  `TestIchimokuRawSpans` (10 tests) for the new indicator features.
+
+---
+
 ## [0.7.1] — 2026-06-18
 
 ### Fixed

{algotradekit-0.7.1 → algotradekit-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AlgoTradeKit
-Version: 0.7.1
+Version: 0.7.2
 Summary: Algorithmic Trading Toolkit — data collection, indicators, strategy, simulation, and live trading
 Project-URL: Homepage, https://github.com/AmirMohammadBazdar/AlgoTradeKit
 Project-URL: Repository, https://github.com/AmirMohammadBazdar/AlgoTradeKit
@@ -125,6 +125,31 @@ import pandas as pd
 data = {"1h": pd.read_csv("data/binance-futures_BTCUSDT_1h.csv")}
 ```
 
+**Normalizing non-standard CSVs** *(v0.7.2)*
+
+Broker / MT5 exports often use Unix-second timestamps and omit optional columns.
+`Normalizer` converts any OHLCV CSV to the library standard automatically:
+
+```python
+from AlgoTradeKit.data import Normalizer
+
+# Accepts: timestamp in seconds OR milliseconds (auto-detected)
+# Required columns: timestamp, open, high, low, close
+# Optional: volume (defaults to 0 if absent)
+norm = Normalizer("USDJPY_1m.csv")
+norm.start = "2022/01/01"   # optional date filter
+norm.end   = "2024/01/01"
+
+# Return as DataFrame (no file written)
+df = norm.normalize()
+
+# Save as library-standard CSV
+path = norm.save(destination="data/")
+
+# One-liner: normalize + save
+df, path = Normalizer("USDJPY_1m.csv").normalize_and_save(destination="data/")
+```
+
 ---
 
 ## indicator — Technical Indicators
@@ -132,20 +157,41 @@ data = {"1h": pd.read_csv("data/binance-futures_BTCUSDT_1h.csv")}
 All indicators are **built from scratch** — no third-party TA wrappers.
 
 ```python
-from AlgoTradeKit.indicator import RSI, MACD, EMA, SMA, BollingerBands, ATR, Ichimoku
+from AlgoTradeKit.indicator import ATR, RSI, MACD, EMA, SMA, Ichimoku
 
 close = df["close"]   # pd.Series
 
-rsi  = RSI(close, length=14)           # rsi.value
+rsi  = RSI(close, length=14)           # rsi.rsi
 macd = MACD(close, fast=12, slow=26, signal=9)
-                                        # macd.macd_line, .signal_line, .histogram
-ema  = EMA(close, length=20)           # ema.value
-sma  = SMA(close, length=50)           # sma.value
-bb   = BollingerBands(close, length=20, std=2.0)
-                                        # bb.upper, .middle, .lower
-atr  = ATR(df["high"], df["low"], close, length=14)  # atr.value
+                                        # macd.macd, .signal, .histogram
+ema  = EMA(close, length=20)           # ema.ema
+sma  = SMA(close, length=50)           # sma.sma
+atr  = ATR(df["high"], df["low"], close, period=14)  # atr.atr, atr.tr
 ichi = Ichimoku(df["high"], df["low"], close)
-                                        # ichi.tenkan/kijun/senkou_a/senkou_b/chikou
+                                        # ichi.tenkan / kijun / senkou_a / senkou_b
+                                        # ichi.chikou / cloud_future_a / cloud_future_b
+                                        # ichi.span_a_raw / span_b_raw  ← v0.7.2
+```
+
+**`ATR` — Average True Range** *(v0.7.2)*
+
+Wilder's smoothing (RMA, `alpha = 1/period`). Matches TradingView `ta.atr()`.
+
+```python
+atr = ATR(df["high"], df["low"], df["close"], period=14)
+df["atr"] = atr.atr.values   # Wilder-smoothed ATR
+df["tr"]  = atr.tr.values    # raw True Range
+```
+
+**`Ichimoku.span_a_raw` / `.span_b_raw`** *(v0.7.2)*
+
+Unshifted Senkou Span A and B (at the current bar, before the displacement shift
+is applied). Useful in strategy logic where you need the live cloud value:
+
+```python
+ichi = Ichimoku(high, low, close, displacement=26)
+# ichi.senkou_a   = span_a_raw.shift(26)  — displayed cloud (forward-shifted)
+# ichi.span_a_raw = (tenkan + kijun) / 2  — current bar value (unshifted)
 ```
 
 ---
@@ -324,6 +370,31 @@ chart = Chart.from_csv("data/binance-futures_BTCUSDT_1h.csv")
 chart.show(block=True)
 ```
 
+**Candle range filter** *(v0.7.2)*
+
+Restrict which candles are visible without modifying the source data:
+
+```python
+# Show a specific datetime range
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"start": "2024/01/01", "end": "2024/06/01"})
+
+# From a date to the last candle
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"start": "2024/06/01"})
+
+# From the first candle to a date
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"end": "2024/01/01"})
+
+# Last / first N candles
+chart = Chart.from_csv("data/btc_1h.csv", candle_range={"last_n": 500})
+chart = Chart.from_csv("data/btc_1h.csv", candle_range={"first_n": 200})
+
+# Also available on set_data()
+chart.set_data(df, candle_range={"start": "2023/01/01", "end": "2024/01/01"})
+```
+
 ### Add Indicators
 
 ```python

{algotradekit-0.7.1 → algotradekit-0.7.2}/README.md

@@ -69,6 +69,31 @@ import pandas as pd
 data = {"1h": pd.read_csv("data/binance-futures_BTCUSDT_1h.csv")}
 ```
 
+**Normalizing non-standard CSVs** *(v0.7.2)*
+
+Broker / MT5 exports often use Unix-second timestamps and omit optional columns.
+`Normalizer` converts any OHLCV CSV to the library standard automatically:
+
+```python
+from AlgoTradeKit.data import Normalizer
+
+# Accepts: timestamp in seconds OR milliseconds (auto-detected)
+# Required columns: timestamp, open, high, low, close
+# Optional: volume (defaults to 0 if absent)
+norm = Normalizer("USDJPY_1m.csv")
+norm.start = "2022/01/01"   # optional date filter
+norm.end   = "2024/01/01"
+
+# Return as DataFrame (no file written)
+df = norm.normalize()
+
+# Save as library-standard CSV
+path = norm.save(destination="data/")
+
+# One-liner: normalize + save
+df, path = Normalizer("USDJPY_1m.csv").normalize_and_save(destination="data/")
+```
+
 ---
 
 ## indicator — Technical Indicators
@@ -76,20 +101,41 @@ data = {"1h": pd.read_csv("data/binance-futures_BTCUSDT_1h.csv")}
 All indicators are **built from scratch** — no third-party TA wrappers.
 
 ```python
-from AlgoTradeKit.indicator import RSI, MACD, EMA, SMA, BollingerBands, ATR, Ichimoku
+from AlgoTradeKit.indicator import ATR, RSI, MACD, EMA, SMA, Ichimoku
 
 close = df["close"]   # pd.Series
 
-rsi  = RSI(close, length=14)           # rsi.value
+rsi  = RSI(close, length=14)           # rsi.rsi
 macd = MACD(close, fast=12, slow=26, signal=9)
-                                        # macd.macd_line, .signal_line, .histogram
-ema  = EMA(close, length=20)           # ema.value
-sma  = SMA(close, length=50)           # sma.value
-bb   = BollingerBands(close, length=20, std=2.0)
-                                        # bb.upper, .middle, .lower
-atr  = ATR(df["high"], df["low"], close, length=14)  # atr.value
+                                        # macd.macd, .signal, .histogram
+ema  = EMA(close, length=20)           # ema.ema
+sma  = SMA(close, length=50)           # sma.sma
+atr  = ATR(df["high"], df["low"], close, period=14)  # atr.atr, atr.tr
 ichi = Ichimoku(df["high"], df["low"], close)
-                                        # ichi.tenkan/kijun/senkou_a/senkou_b/chikou
+                                        # ichi.tenkan / kijun / senkou_a / senkou_b
+                                        # ichi.chikou / cloud_future_a / cloud_future_b
+                                        # ichi.span_a_raw / span_b_raw  ← v0.7.2
+```
+
+**`ATR` — Average True Range** *(v0.7.2)*
+
+Wilder's smoothing (RMA, `alpha = 1/period`). Matches TradingView `ta.atr()`.
+
+```python
+atr = ATR(df["high"], df["low"], df["close"], period=14)
+df["atr"] = atr.atr.values   # Wilder-smoothed ATR
+df["tr"]  = atr.tr.values    # raw True Range
+```
+
+**`Ichimoku.span_a_raw` / `.span_b_raw`** *(v0.7.2)*
+
+Unshifted Senkou Span A and B (at the current bar, before the displacement shift
+is applied). Useful in strategy logic where you need the live cloud value:
+
+```python
+ichi = Ichimoku(high, low, close, displacement=26)
+# ichi.senkou_a   = span_a_raw.shift(26)  — displayed cloud (forward-shifted)
+# ichi.span_a_raw = (tenkan + kijun) / 2  — current bar value (unshifted)
 ```
 
 ---
@@ -268,6 +314,31 @@ chart = Chart.from_csv("data/binance-futures_BTCUSDT_1h.csv")
 chart.show(block=True)
 ```
 
+**Candle range filter** *(v0.7.2)*
+
+Restrict which candles are visible without modifying the source data:
+
+```python
+# Show a specific datetime range
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"start": "2024/01/01", "end": "2024/06/01"})
+
+# From a date to the last candle
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"start": "2024/06/01"})
+
+# From the first candle to a date
+chart = Chart.from_csv("data/btc_1h.csv",
+    candle_range={"end": "2024/01/01"})
+
+# Last / first N candles
+chart = Chart.from_csv("data/btc_1h.csv", candle_range={"last_n": 500})
+chart = Chart.from_csv("data/btc_1h.csv", candle_range={"first_n": 200})
+
+# Also available on set_data()
+chart.set_data(df, candle_range={"start": "2023/01/01", "end": "2024/01/01"})
+```
+
 ### Add Indicators
 
 ```python

{algotradekit-0.7.1 → algotradekit-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "AlgoTradeKit"
-version = "0.7.1"
+version = "0.7.2"
 description = "Algorithmic Trading Toolkit — data collection, indicators, strategy, simulation, and live trading"
 readme = "README.md"
 license = { file = "LICENSE" }

{algotradekit-0.7.1 → algotradekit-0.7.2}/src/AlgoTradeKit/__init__.py

@@ -1,4 +1,4 @@
 """AlgoTradeKit — Algorithmic Trading Toolkit"""
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 __author__ = "Amir Mohammad Bazdar"

{algotradekit-0.7.1 → algotradekit-0.7.2}/src/AlgoTradeKit/data/__init__.py

@@ -1,5 +1,6 @@
 from .collector import Collector
 from .converter import Converter
+from .normalizer import Normalizer
 from .sources import get_source
 from .sources.base import BaseSource
 from .sources.binance import BinanceSource
@@ -8,6 +9,7 @@ from .storage.csv_handler import CSVHandler
 __all__ = [
     "Collector",
     "Converter",
+    "Normalizer",
     "get_source",
     "BaseSource",
     "BinanceSource",