Provider abstraction: providers/ package with BaseDataProvider template

One class per provider (TwelveData, Oanda, Tiingo), all subclassing
BaseDataProvider which owns cache, validation/cleaning, freshness +
boundary guarantees, fetch_range pagination, and streaming stubs —
subclasses implement only _fetch_raw. config.json data_providers.active
selects the live feed; data_provider.py / oanda_provider.py stay as
back-compat shims. Module 16 provider-abstraction tests (253 total green).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mc7XKYyPySVXiUpcN82QEK
This commit is contained in:
Harwinder Sekhon
2026-07-28 20:09:00 -04:00
parent 95f8c47d4f
commit c8beb7e3ae
17 changed files with 1573 additions and 935 deletions
+54
View File
@@ -0,0 +1,54 @@
"""
ForexBot2 — Data-provider package
==================================
One class per provider, all subclassing `BaseDataProvider` (which owns
caching, validation, boundary guarantees, and range pagination — the
behavior the signal pipeline depends on).
Adding a provider = one module implementing `_fetch_raw` + one registry
entry + one config.json `data_providers` block. The live feed is selected
by config.json `data_providers.active`; registration alone changes
nothing.
"""
from typing import Dict
from app_config import AppConfigError, get_app_config
from config import PlatformConfig
from providers.base import BaseDataProvider, DataIntegrityError, _is_forex_weekend
from providers.twelve_data import TwelveDataProvider
from providers.oanda import OandaDataError, OandaDataProvider
from providers.tiingo import TiingoDataError, TiingoDataProvider
#: config.json data_providers.active selects from here.
PROVIDER_REGISTRY: Dict[str, type] = {
"twelve_data": TwelveDataProvider,
"oanda": OandaDataProvider,
"tiingo": TiingoDataProvider,
}
def make_data_provider(config: PlatformConfig) -> BaseDataProvider:
"""Build the ACTIVE data provider (config.json: data_providers.active)."""
name = get_app_config().active_provider
cls = PROVIDER_REGISTRY.get(name)
if cls is None:
raise AppConfigError(
f'Unknown data provider "{name}"; '
f"registered: {sorted(PROVIDER_REGISTRY)}")
return cls(config)
__all__ = [
"BaseDataProvider",
"DataIntegrityError",
"OandaDataError",
"OandaDataProvider",
"TiingoDataError",
"TiingoDataProvider",
"TwelveDataProvider",
"PROVIDER_REGISTRY",
"make_data_provider",
"_is_forex_weekend",
]
+423
View File
@@ -0,0 +1,423 @@
"""
ForexBot2 — Provider base class
================================
`BaseDataProvider` owns everything that must behave identically no matter
where the bars come from: in-memory caching with candle-duration TTL, the
closed-bar boundary guarantee, freshness checks, validation/cleaning, the
forming-candle drop, and paginated date-range fetching for the backtester.
A concrete provider implements only:
_fetch_raw(symbol, timeframe, outputsize, start, end) -> pd.DataFrame
returning a normalized frame (capitalized OHLCV columns, UTC tz-aware
DatetimeIndex named "Datetime", oldest-first), plus optionally
`get_spread` and the streaming-quote capability (`supports_streaming` +
`iter_ticks`).
The signal pipeline (engine + aggregator + backtester) consumes ONLY the
public contract defined here, so swapping providers never touches signal
code.
"""
import logging
import threading
import time
from abc import ABC, abstractmethod
from datetime import datetime, timedelta
from typing import AsyncIterator, Callable, Dict, Optional, Sequence, Tuple
import pandas as pd
from config import PAIR_INFO, PlatformConfig, Timeframe, XAUUSD
logger = logging.getLogger(__name__)
def _is_forex_weekend(now=None) -> bool:
"""Forex market closed: Friday 22:00 UTC → Sunday 22:00 UTC."""
if now is None:
now = pd.Timestamp.now(tz="UTC")
wd = now.weekday()
hour = now.hour
if wd == 4 and hour >= 22:
return True
if wd == 5:
return True
if wd == 6 and hour < 22:
return True
return False
class DataIntegrityError(Exception):
"""Raised when data fails validation checks."""
pass
class BaseDataProvider(ABC):
"""Shared OHLCV provider behavior; subclasses supply the raw fetch."""
#: Registry name; overridden per provider.
name: str = "base"
#: Exception type this provider raises for fetch/validation failures.
#: Provider-specific errors subclass DataIntegrityError so consumers
#: can catch one type regardless of the active provider.
DATA_ERROR = DataIntegrityError
BARS_PER_DAY = {
Timeframe.M1: 1440, Timeframe.M5: 288, Timeframe.M15: 96,
Timeframe.M30: 48, Timeframe.H1: 24, Timeframe.H4: 6,
Timeframe.D1: 1, Timeframe.W1: 0.143,
}
CANDLE_SECONDS = {
Timeframe.M1: 60, Timeframe.M5: 300, Timeframe.M15: 900,
Timeframe.M30: 1800, Timeframe.H1: 3600, Timeframe.H4: 14400,
Timeframe.D1: 86400, Timeframe.W1: 604800,
}
#: Hard per-request bar cap shared by Twelve Data and Oanda.
MAX_BARS_PER_REQUEST = 5000
# Grace wait before the one retry when a fresh response at a candle
# boundary is missing the just-closed bar (feed latency).
FRESH_FETCH_RETRY_SECONDS = 3.0
def __init__(self, config: PlatformConfig):
self.config = config
self._cache: Dict[str, pd.DataFrame] = {}
self._cache_timestamps: Dict[str, float] = {}
# The bot shares one provider across a thread pool; cache eviction
# is check-then-act and needs locking.
self._cache_lock = threading.Lock()
# ── Abstract: the only provider-specific piece ─────────────────
@abstractmethod
def _fetch_raw(
self,
symbol: str,
timeframe: Timeframe,
outputsize: int,
start: Optional[datetime] = None,
end: Optional[datetime] = None,
) -> pd.DataFrame:
"""Fetch up to `outputsize` bars, optionally bounded by start/end
(tz-aware UTC datetimes). Must return a normalized frame:
capitalized OHLCV columns, UTC DatetimeIndex named "Datetime",
oldest-first. Raise self.DATA_ERROR on failure."""
# ── Public API ─────────────────────────────────────────────────
def fetch_ohlcv(
self,
symbol: str = XAUUSD,
timeframe: Timeframe = Timeframe.H1,
lookback_days: Optional[int] = None,
) -> pd.DataFrame:
"""Fetch OHLCV with in-memory caching for live mode."""
if lookback_days is None:
lookback_days = self.config.data_lookback_days
cache_key = f"{symbol}_{timeframe.value}"
now = time.time()
cache_ttl = self.CANDLE_SECONDS.get(timeframe, self.config.refresh_interval)
with self._cache_lock:
cached = self._cache.get(cache_key)
cached_at = self._cache_timestamps.get(cache_key)
if (
cached is not None
and cached_at is not None
and (now - cached_at) < cache_ttl
and not cached.empty
):
if (self._is_data_fresh(cached, symbol, timeframe)
and self._has_latest_closed_bar(cached, timeframe)):
return cached
logger.warning(f"{symbol} {timeframe.value}: cached data is stale, refetching")
with self._cache_lock:
self._cache.pop(cache_key, None)
self._cache_timestamps.pop(cache_key, None)
outputsize = max(
300,
min(int(lookback_days * self.BARS_PER_DAY[timeframe]) + 20,
self.MAX_BARS_PER_REQUEST),
)
df = self._fetch_raw(symbol, timeframe, outputsize)
df = self._drop_forming_candle(df, timeframe)
df = self._validate_and_clean(df, symbol, timeframe)
# The closed-bar guarantee must hold for FRESH responses too, not
# just cache hits: the scanner fires seconds after the boundary,
# and a lagging feed can answer without the just-closed bar — the
# scan would silently analyze (and session-check) the previous
# bar. Give the feed one short grace retry, then proceed loudly.
if not df.empty and not self._has_latest_closed_bar(df, timeframe):
time.sleep(self.FRESH_FETCH_RETRY_SECONDS)
try:
retry = self._fetch_raw(symbol, timeframe, outputsize)
retry = self._drop_forming_candle(retry, timeframe)
retry = self._validate_and_clean(retry, symbol, timeframe)
if retry is not None and not retry.empty:
df = retry
except DataIntegrityError as e:
logger.warning(
f"{symbol} {timeframe.value}: boundary retry refetch "
f"failed ({e}) — keeping original data")
if not self._has_latest_closed_bar(df, timeframe):
logger.warning(
f"{symbol} {timeframe.value}: feed lagging — just-closed bar "
f"still missing after retry; this scan may run one bar behind"
)
if not self._is_data_fresh(df, symbol, timeframe):
logger.warning(
f"STALE DATA from API: {symbol} {timeframe.value} — "
f"last bar {df.index[-1]} is too old. Signal quality may be degraded."
)
with self._cache_lock:
self._cache[cache_key] = df
self._cache_timestamps[cache_key] = now
return df
def fetch_range(
self,
symbol: str,
timeframe: Timeframe,
start: datetime,
end: datetime,
) -> pd.DataFrame:
"""Fetch the RAW closed-bar series between start/end, paginating
under the per-request bar cap. Returns uncleaned bars (the
backtester resolves trades on the raw price path); callers wanting
the signal-side series run `validate_and_clean` on the result."""
bars_per_day = self.BARS_PER_DAY[timeframe]
days_per_chunk = max(1, int(4500 / bars_per_day))
chunks = []
cursor_end = end
empty_streak = 0
while cursor_end > start:
cursor_start = max(start, cursor_end - timedelta(days=days_per_chunk))
try:
chunk = self._fetch_raw(
symbol, timeframe, self.MAX_BARS_PER_REQUEST,
start=cursor_start, end=cursor_end,
)
except Exception as e:
# Providers raise for windows with no data (weekends,
# holidays, asset gaps). Skip the window, step back, retry
# — but bail after a few consecutive empties.
logger.warning(
f"Chunk {cursor_start.date()}–{cursor_end.date()} failed: {e}"
)
empty_streak += 1
if empty_streak >= 3:
break
cursor_end = cursor_start - timedelta(seconds=1)
continue
if chunk is None or chunk.empty:
empty_streak += 1
if empty_streak >= 3:
break
cursor_end = cursor_start - timedelta(seconds=1)
continue
empty_streak = 0
chunks.append(chunk)
# Step back; dedup on concat.
cursor_end = chunk.index[0] - timedelta(seconds=1)
if len(chunk) < 2:
break
if not chunks:
raise RuntimeError(f"No data fetched for {symbol} {timeframe.value}")
df = pd.concat(chunks).sort_index()
df = df[~df.index.duplicated(keep="last")]
# Fetches ending "now" include the still-forming candle — drop it
# so callers only ever see closed bars.
df = self._drop_forming_candle(df, timeframe)
start_ts = pd.Timestamp(start)
end_ts = pd.Timestamp(end)
return df[(df.index >= start_ts) & (df.index <= end_ts)]
def is_data_fresh(
self, df: pd.DataFrame, symbol: str, timeframe: Timeframe
) -> bool:
"""Public freshness check (last bar within 3 candle durations)."""
return self._is_data_fresh(df, symbol, timeframe)
def validate_and_clean(
self, df: pd.DataFrame, symbol: str, timeframe: Timeframe
) -> pd.DataFrame:
"""Public entry to the shared cleaning pipeline."""
return self._validate_and_clean(df, symbol, timeframe)
def clear_cache(self) -> int:
"""Wipe all cached data. Returns number of entries cleared."""
with self._cache_lock:
count = len(self._cache)
self._cache.clear()
self._cache_timestamps.clear()
logger.info(f"Cache cleared: {count} entries wiped")
return count
def get_pair_info(self, symbol: str = XAUUSD) -> Dict:
info = PAIR_INFO.get(symbol, PAIR_INFO[XAUUSD])
return {"symbol": symbol, **info}
def get_spread(self, symbol: str = XAUUSD) -> float:
"""Latest observed round-trip spread; providers without live
bid/ask fall back to the pair's assumed default."""
return PAIR_INFO.get(symbol, PAIR_INFO[XAUUSD])["default_spread"]
# ── Streaming-quote capability (optional) ──────────────────────
#: True when the provider can stream live ticks via `iter_ticks`.
supports_streaming: bool = False
def iter_ticks(
self,
symbols: Sequence[str],
on_connect: Optional[Callable[[], None]] = None,
) -> AsyncIterator[Tuple[str, float]]:
"""Async generator yielding (canonical_symbol, price) ticks for one
connection's lifetime; the caller owns reconnect/backoff. Providers
that support it set `supports_streaming = True` and override."""
raise NotImplementedError(
f"{self.name} provider does not support streaming quotes")
# ── Shared internals ───────────────────────────────────────────
def _has_latest_closed_bar(self, df: pd.DataFrame, timeframe: Timeframe) -> bool:
"""Cached data must include the most recent fully closed bar.
The TTL alone is wall-clock based: a snapshot fetched mid-candle is
still within TTL at the next candle boundary but is missing the bar
that just closed, so every boundary scan would analyze — and run the
bar-close session check against — the previous bar.
"""
if df is None or df.empty:
return False
now = pd.Timestamp.now(tz="UTC")
if _is_forex_weekend(now):
return True
candle_seconds = self.CANDLE_SECONDS.get(timeframe, 3600)
dur = pd.Timedelta(seconds=candle_seconds)
expected_label = now.floor(dur) - dur
return df.index[-1] >= expected_label
def _drop_forming_candle(self, df: pd.DataFrame, timeframe: Timeframe) -> pd.DataFrame:
"""Drop the still-forming last candle so analysis only sees closed bars.
Some feeds include the current partial candle; the scanner fires
seconds after the boundary, so without this guard every indicator
reads a seconds-old stub bar and signals repaint. Feeds that only
return complete candles pass through unchanged.
"""
if df is None or df.empty:
return df
candle_seconds = self.CANDLE_SECONDS.get(timeframe, 3600)
now = pd.Timestamp.now(tz="UTC")
if df.index[-1] + pd.Timedelta(seconds=candle_seconds) > now:
df = df.iloc[:-1]
return df
def _is_data_fresh(self, df: pd.DataFrame, symbol: str, timeframe: Timeframe) -> bool:
"""Check if the last candle is within acceptable age for this timeframe."""
if df is None or df.empty:
return False
now = pd.Timestamp.now(tz="UTC")
if _is_forex_weekend(now):
return True
last_bar = df.index[-1]
candle_seconds = self.CANDLE_SECONDS.get(timeframe, 3600)
max_age_seconds = candle_seconds * 3
age_seconds = (now - last_bar).total_seconds()
if age_seconds > max_age_seconds:
logger.warning(
f"{symbol} {timeframe.value}: last bar {last_bar.strftime('%Y-%m-%d %H:%M')} "
f"is {age_seconds / 60:.0f}m old (limit: {max_age_seconds / 60:.0f}m)"
)
return False
return True
def _validate_and_clean(
self, df: pd.DataFrame, symbol: str, timeframe: Timeframe
) -> pd.DataFrame:
if df is None or df.empty:
raise self.DATA_ERROR(f"Empty dataset for {symbol}")
original_len = len(df)
df = df.dropna(subset=["Open", "High", "Low", "Close"], how="all")
df = df.ffill(limit=3)
df = df.dropna(subset=["Close"])
df = df.sort_index()
df = df[~df.index.duplicated(keep="last")]
now = pd.Timestamp.utcnow()
future_mask = df.index > now + pd.Timedelta(minutes=5)
if future_mask.any():
logger.warning(f"{symbol}: Dropping {future_mask.sum()} future timestamps")
df = df[~future_mask]
invalid_ohlc = (
(df["High"] < df["Low"]) |
(df["High"] < df["Open"]) |
(df["High"] < df["Close"]) |
(df["Low"] > df["Open"]) |
(df["Low"] > df["Close"])
)
if invalid_ohlc.any():
logger.warning(f"{symbol}: Fixing {invalid_ohlc.sum()} OHLC-inconsistent bars")
for idx in df[invalid_ohlc].index:
vals = [df.loc[idx, "Open"], df.loc[idx, "Close"]]
df.loc[idx, "High"] = max(vals + [df.loc[idx, "High"]])
df.loc[idx, "Low"] = min(vals + [df.loc[idx, "Low"]])
returns = df["Close"].pct_change()
std_ret = returns.std()
if std_ret > 0:
dev = returns - returns.mean()
outlier_mask = dev.abs() > 10 * std_ret
# A spike bar makes the NEXT bar's return look extreme too (it is
# measured against the spike). If the previous bar is flagged and
# this bar reverses direction, it is the legitimate snap-back —
# keep it, or every spike would punch a two-bar hole in the data.
recovery = (
outlier_mask
& outlier_mask.shift(1, fill_value=False)
& (dev * dev.shift(1) < 0)
)
outlier_mask = outlier_mask & ~recovery
if outlier_mask.any():
logger.warning(f"{symbol}: Removing {outlier_mask.sum()} extreme outlier bars")
df = df[~outlier_mask]
min_required = max(
self.config.technical.ema_trend,
200,
) + 10
if len(df) < min_required:
logger.warning(
f"{symbol} {timeframe.value}: Only {len(df)} bars "
f"(need {min_required}). Some indicators will be partial."
)
cleaned = original_len - len(df)
if cleaned > 0:
logger.info(f"{symbol}: Cleaned {cleaned}/{original_len} bars")
return df
+192
View File
@@ -0,0 +1,192 @@
"""
ForexBot2 — Oanda v20 data provider
====================================
OHLCV candles from the Oanda v20 REST API. All shared behavior (cache,
validation, boundary guarantees, range pagination) lives in
`BaseDataProvider`; this module only maps symbols/granularities, parses
Oanda's candle JSON, and exposes the real bid/ask spread from MBA candles.
"""
import logging
from datetime import datetime
from typing import Dict, Optional
import pandas as pd
import requests
from app_config import oanda_api_token, oanda_base_url
from config import PAIR_INFO, PlatformConfig, Timeframe, XAUUSD
from providers.base import BaseDataProvider, DataIntegrityError
logger = logging.getLogger(__name__)
class OandaDataError(DataIntegrityError):
"""Raised when an Oanda data fetch fails or returns invalid data."""
class OandaDataProvider(BaseDataProvider):
"""Oanda v20 REST candle provider."""
name = "oanda"
DATA_ERROR = OandaDataError
OANDA_GRANULARITY = {
Timeframe.M1: "M1",
Timeframe.M5: "M5",
Timeframe.M15: "M15",
Timeframe.M30: "M30",
Timeframe.H1: "H1",
Timeframe.H4: "H4",
Timeframe.D1: "D",
Timeframe.W1: "W",
}
OANDA_INSTRUMENT = {
"XAU/USD": "XAU_USD",
}
def __init__(
self,
config: PlatformConfig,
api_token: Optional[str] = None,
base_url: Optional[str] = None,
):
super().__init__(config)
# Credentials default to the config.json `oanda` block / env vars
# so the provider registry can build this class with config only.
if api_token is None:
api_token = oanda_api_token()
if base_url is None:
base_url = oanda_base_url()
self._base_url = base_url.rstrip("/")
self._session = requests.Session()
self._session.headers.update({
"Authorization": f"Bearer {api_token}",
"Accept-Datetime-Format": "RFC3339",
"Content-Type": "application/json",
})
self._spread_cache: Dict[str, float] = {}
# ── Public extras ──────────────────────────────────────────────
def get_spread(self, symbol: str = XAUUSD) -> float:
return self._spread_cache.get(
symbol, PAIR_INFO.get(symbol, PAIR_INFO[XAUUSD])["default_spread"])
# ── Raw fetch ──────────────────────────────────────────────────
def _fetch_raw(
self,
symbol: str,
timeframe: Timeframe,
outputsize: int,
start: Optional[datetime] = None,
end: Optional[datetime] = None,
) -> pd.DataFrame:
if start is not None or end is not None:
return self._fetch_oanda_candles(
symbol, timeframe, outputsize, start, end)
return self._fetch_oanda_candles(symbol, timeframe, outputsize)
def _to_oanda_instrument(self, symbol: str) -> str:
if symbol in self.OANDA_INSTRUMENT:
return self.OANDA_INSTRUMENT[symbol]
return symbol.replace("/", "_")
def _fetch_oanda_candles(
self,
symbol: str,
timeframe: Timeframe,
count: int,
start: Optional[datetime] = None,
end: Optional[datetime] = None,
) -> pd.DataFrame:
instrument = self._to_oanda_instrument(symbol)
granularity = self.OANDA_GRANULARITY.get(timeframe)
if granularity is None:
raise OandaDataError(
f"Unsupported timeframe {timeframe} for Oanda")
url = f"{self._base_url}/v3/instruments/{instrument}/candles"
params = {
"granularity": granularity,
"price": "MBA",
"dailyAlignment": 0,
"alignmentTimezone": "Etc/UTC",
}
# v20 rejects `count` combined with both `from` and `to`; a date
# window replaces it (used by fetch_range pagination).
if start is not None and end is not None:
params["from"] = pd.Timestamp(start).isoformat()
params["to"] = pd.Timestamp(end).isoformat()
else:
params["count"] = min(count, self.MAX_BARS_PER_REQUEST)
try:
resp = self._session.get(url, params=params, timeout=30)
except requests.RequestException as e:
raise OandaDataError(
f"Oanda candle fetch failed for {instrument}: {e}") from e
if resp.status_code != 200:
raise OandaDataError(
f"Oanda candle fetch failed for {instrument}: "
f"HTTP {resp.status_code}: {resp.text[:300]}")
try:
data = resp.json()
except ValueError as e:
raise OandaDataError(
f"Oanda candle response for {instrument} is not valid "
f"JSON: {e}") from e
candles = data.get("candles", [])
if not candles:
raise OandaDataError(
f"Empty candle response from Oanda for {instrument}")
rows = []
last_bid_close = None
last_ask_close = None
for c in candles:
if not c.get("complete", False):
continue
mid = c.get("mid", {})
bid = c.get("bid", {})
ask = c.get("ask", {})
rows.append({
"Datetime": pd.Timestamp(c["time"]).tz_convert("UTC"),
"Open": float(mid.get("o", 0)),
"High": float(mid.get("h", 0)),
"Low": float(mid.get("l", 0)),
"Close": float(mid.get("c", 0)),
"Volume": int(c.get("volume", 0)),
})
if bid and ask:
last_bid_close = float(bid.get("c", 0))
last_ask_close = float(ask.get("c", 0))
if not rows:
raise OandaDataError(
f"No complete candles from Oanda for {instrument}")
if last_bid_close and last_ask_close:
self._spread_cache[symbol] = round(
last_ask_close - last_bid_close, 4)
df = pd.DataFrame(rows)
df = df.set_index("Datetime")
df = df.sort_index()
if df.index.tz is None:
df.index = df.index.tz_localize("UTC")
df.index.name = "Datetime"
for col in ("Open", "High", "Low", "Close"):
df[col] = pd.to_numeric(df[col], errors="coerce")
df["Volume"] = pd.to_numeric(df["Volume"], errors="coerce").fillna(0).astype(float)
logger.debug(
"Fetched %d bars for %s @ %s from Oanda",
len(df), instrument, granularity)
return df
+200
View File
@@ -0,0 +1,200 @@
"""
ForexBot2 — Tiingo data provider
=================================
OHLCV candles from Tiingo's FX endpoint
(`/tiingo/fx/{ticker}/prices`, resampled mid-price bars, no volume).
All shared behavior (cache, validation, boundary guarantees, range
pagination) lives in `BaseDataProvider`; this module only maps
symbols/resample frequencies, sizes the request window, and parses
Tiingo's JSON into the normalized frame.
Every failure mode raises `TiingoDataError` (a `DataIntegrityError`)
with a specific message — the scan loops log it and carry on; nothing
fails silently. NOTE: this is the CANDLE feed only. Tiingo's free
`/tiingo/fx/top` quote endpoint publishes indicative two-tier spreads
and must not be used for spread display (removed 2026-07-23) —
`get_spread` deliberately stays on the base-class default.
"""
import logging
from datetime import datetime
from typing import Optional
import pandas as pd
import requests
from app_config import provider_api_key
from config import PlatformConfig, Timeframe
from providers.base import BaseDataProvider, DataIntegrityError
logger = logging.getLogger(__name__)
class TiingoDataError(DataIntegrityError):
"""Raised when a Tiingo data fetch fails or returns invalid data."""
class TiingoDataProvider(BaseDataProvider):
"""Tiingo FX REST candle provider."""
name = "tiingo"
DATA_ERROR = TiingoDataError
BASE_URL = "https://api.tiingo.com"
TIINGO_RESAMPLE = {
Timeframe.M1: "1min",
Timeframe.M5: "5min",
Timeframe.M15: "15min",
Timeframe.M30: "30min",
Timeframe.H1: "1hour",
Timeframe.H4: "4hour",
Timeframe.D1: "1day",
# W1 intentionally unmapped: the FX endpoint has no weekly
# resample — requesting it raises loudly instead of guessing.
}
TIINGO_TICKER = {
"XAU/USD": "xauusd",
}
# Window padding over the theoretical bar span: FX is closed ~2/7 of
# the week (Fri 22:00 → Sun 22:00 UTC), so a calendar window must be
# wider than `bars × candle_seconds` to yield the requested count.
WINDOW_PAD_FACTOR = 1.6
def __init__(self, config: PlatformConfig, api_key: Optional[str] = None):
super().__init__(config)
# Credentials default to env TIINGO_API_KEY → config.json
# data_providers.tiingo.api_key, so the provider registry can
# build this class with config only.
if api_key is None:
api_key = provider_api_key(provider="tiingo")
self._api_key = api_key or None
if self._api_key is None:
logger.warning(
"Tiingo provider built WITHOUT an API key — every fetch "
"will fail with a named error. Set the TIINGO_API_KEY env "
"var or data_providers.tiingo.api_key in config.json.")
self._session = requests.Session()
self._session.headers.update({
"Content-Type": "application/json",
# Header auth keeps the key out of URLs (and out of logs).
"Authorization": f"Token {api_key}" if api_key else "",
})
def _to_tiingo_ticker(self, symbol: str) -> str:
if symbol in self.TIINGO_TICKER:
return self.TIINGO_TICKER[symbol]
return symbol.replace("/", "").replace("=X", "").lower()
# ── Raw fetch ──────────────────────────────────────────────────
def _fetch_raw(
self,
symbol: str,
timeframe: Timeframe,
outputsize: int,
start: Optional[datetime] = None,
end: Optional[datetime] = None,
) -> pd.DataFrame:
if self._api_key is None:
raise TiingoDataError(
"No Tiingo API key. Set the TIINGO_API_KEY env var or "
"data_providers.tiingo.api_key in config.json.")
resample = self.TIINGO_RESAMPLE.get(timeframe)
if resample is None:
raise TiingoDataError(
f"Unsupported timeframe {timeframe} for Tiingo "
f"(no FX resample frequency)")
ticker = self._to_tiingo_ticker(symbol)
# Tiingo takes date windows, not bar counts: derive the start
# from the requested count for live fetches.
if start is None:
span = self.CANDLE_SECONDS[timeframe] * (outputsize + 10)
start_ts = (pd.Timestamp.now(tz="UTC")
- pd.Timedelta(seconds=span * self.WINDOW_PAD_FACTOR))
else:
start_ts = pd.Timestamp(start)
params = {
"resampleFreq": resample,
"startDate": start_ts.strftime("%Y-%m-%dT%H:%M:%S"),
}
if end is not None:
params["endDate"] = pd.Timestamp(end).strftime("%Y-%m-%dT%H:%M:%S")
url = f"{self.BASE_URL}/tiingo/fx/{ticker}/prices"
try:
resp = self._session.get(url, params=params, timeout=30)
except requests.RequestException as e:
raise TiingoDataError(
f"Tiingo candle fetch failed for {ticker}: {e}") from e
if resp.status_code == 429:
raise TiingoDataError(
f"Tiingo rate limit hit for {ticker} (HTTP 429) — "
f"plan quota exhausted; scan will retry next boundary")
if resp.status_code in (401, 403):
raise TiingoDataError(
f"Tiingo auth failed for {ticker} (HTTP {resp.status_code}) "
f"— check TIINGO_API_KEY / config.json api_key")
if resp.status_code != 200:
raise TiingoDataError(
f"Tiingo candle fetch failed for {ticker}: "
f"HTTP {resp.status_code}: {resp.text[:300]}")
try:
data = resp.json()
except ValueError as e:
raise TiingoDataError(
f"Tiingo candle response for {ticker} is not valid "
f"JSON: {e}") from e
if not isinstance(data, list) or not data:
raise TiingoDataError(
f"Empty candle response from Tiingo for {ticker} "
f"(window {params['startDate']} → "
f"{params.get('endDate', 'now')}; check ticker and plan "
f"history limits)")
rows = []
for item in data:
if "date" not in item:
raise TiingoDataError(
f"Malformed Tiingo candle for {ticker}: missing "
f"'date' in {str(item)[:120]}")
rows.append({
"Datetime": pd.Timestamp(item["date"]),
"Open": item.get("open"),
"High": item.get("high"),
"Low": item.get("low"),
"Close": item.get("close"),
# FX endpoint has no volume; 0.0 keeps the engine contract.
"Volume": 0.0,
})
df = pd.DataFrame(rows)
df = df.set_index("Datetime")
df = df.sort_index()
if df.index.tz is None:
df.index = df.index.tz_localize("UTC")
else:
df.index = df.index.tz_convert("UTC")
df.index.name = "Datetime"
for col in ("Open", "High", "Low", "Close"):
df[col] = pd.to_numeric(df[col], errors="coerce")
if df["Close"].isna().all():
raise TiingoDataError(
f"Tiingo response for {ticker} has no numeric closes — "
f"feed format changed?")
logger.debug(
"Fetched %d bars for %s @ %s from Tiingo",
len(df), ticker, resample)
return df
+238
View File
@@ -0,0 +1,238 @@
"""
ForexBot2 — Twelve Data provider
=================================
OHLCV via the official `twelvedata` SDK plus streaming quotes over the
Twelve Data WebSocket. All shared behavior (cache, validation, boundary
guarantees, range pagination) lives in `BaseDataProvider`.
"""
import asyncio
import json
import logging
import threading
import time
from collections import deque
from datetime import datetime
from typing import AsyncIterator, Callable, Optional, Sequence, Tuple
import pandas as pd
from twelvedata import TDClient
from app_config import provider_api_key
from config import PAIR_INFO, PlatformConfig, Timeframe
from providers.base import BaseDataProvider, DataIntegrityError
logger = logging.getLogger(__name__)
class TwelveDataProvider(BaseDataProvider):
"""Twelve Data SDK client with credit throttling and WS quotes."""
name = "twelve_data"
TD_INTERVALS = {
Timeframe.M1: "1min",
Timeframe.M5: "5min",
Timeframe.M15: "15min",
Timeframe.M30: "30min",
Timeframe.H1: "1h",
Timeframe.H4: "4h",
Timeframe.D1: "1day",
Timeframe.W1: "1week",
}
RATE_LIMIT = 55
RATE_WINDOW = 60.0
WS_URL = "wss://ws.twelvedata.com/v1/quotes/price?apikey={api_key}"
def __init__(self, config: PlatformConfig):
super().__init__(config)
self._api_key = provider_api_key(provider="twelve_data") or None
self._throttle_lock = threading.Lock()
self._request_times: deque = deque()
self._td: Optional[TDClient] = (
TDClient(apikey=self._api_key) if self._api_key else None
)
@staticmethod
def _to_td_symbol(symbol: str) -> str:
if "/" in symbol:
return symbol
clean = symbol.replace("=X", "")
return f"{clean[:3]}/{clean[3:]}"
# ── Raw fetch ──────────────────────────────────────────────────
def _fetch_raw(
self,
symbol: str,
timeframe: Timeframe,
outputsize: int,
start: Optional[datetime] = None,
end: Optional[datetime] = None,
) -> pd.DataFrame:
return self._fetch_twelve_data(
symbol, timeframe, outputsize,
start_date=start.strftime("%Y-%m-%d %H:%M:%S") if start else None,
end_date=end.strftime("%Y-%m-%d %H:%M:%S") if end else None,
)
def _throttle(self, credits: int = 1) -> None:
"""Pro tier: 55 credits / minute. Block until budget allows."""
while True:
with self._throttle_lock:
now = time.time()
while self._request_times and now - self._request_times[0] >= self.RATE_WINDOW:
self._request_times.popleft()
available = self.RATE_LIMIT - len(self._request_times)
if available >= credits:
for _ in range(credits):
self._request_times.append(time.time())
return
used = len(self._request_times)
wait = (self._request_times[0] + self.RATE_WINDOW) - now + 0.2
logger.info(
f"Rate limit: {used}/{self.RATE_LIMIT} credits used "
f"— waiting {wait:.1f}s..."
)
time.sleep(wait)
def _fetch_twelve_data(
self,
symbol: str,
timeframe: Timeframe,
outputsize: int,
start_date: Optional[str] = None,
end_date: Optional[str] = None,
) -> pd.DataFrame:
if self._td is None:
raise DataIntegrityError(
"No data-provider API key. Set the TWELVE_DATA_API_KEY env "
"var or data_providers.twelve_data.api_key in config.json."
)
td_symbol = self._to_td_symbol(symbol)
interval = self.TD_INTERVALS[timeframe]
self._throttle(credits=1)
kwargs = {
"symbol": td_symbol,
"interval": interval,
"outputsize": min(outputsize, self.MAX_BARS_PER_REQUEST),
"timezone": "UTC",
}
if start_date:
kwargs["start_date"] = start_date
if end_date:
kwargs["end_date"] = end_date
try:
df = self._td.time_series(**kwargs).as_pandas()
except Exception as e:
raise DataIntegrityError(
f"Twelve Data fetch failed for {td_symbol}: {e}"
) from e
if df is None or df.empty:
raise DataIntegrityError(f"Empty response from Twelve Data for {td_symbol}")
# SDK returns lowercase columns; engine expects capitalised.
df = df.rename(columns={
"open": "Open", "high": "High", "low": "Low",
"close": "Close", "volume": "Volume",
})
for col in ("Open", "High", "Low", "Close", "Volume"):
if col in df.columns:
df[col] = pd.to_numeric(df[col], errors="coerce")
if "Volume" not in df.columns:
df["Volume"] = 0.0
# SDK returns newest-first; engine + indicators want oldest-first.
df = df.sort_index()
if df.index.tz is None:
df.index = df.index.tz_localize("UTC")
df.index.name = "Datetime"
logger.debug(f"Fetched {len(df)} bars for {td_symbol} @ {interval}")
return df
# ── Streaming quotes ───────────────────────────────────────────
supports_streaming = True
@staticmethod
def _parse_ws_price(raw: str) -> Optional[Tuple[str, float]]:
"""Parse one WS message; return (ws_symbol, price) for price
events, None for everything else (logged where noteworthy)."""
try:
msg = json.loads(raw)
except json.JSONDecodeError:
logger.warning("WebSocket: malformed JSON, skipping")
return None
event = msg.get("event")
if event == "subscribe-status":
fails = msg.get("fails") or []
if fails:
logger.warning(f"WebSocket: failed to subscribe: {fails}")
return None
if event != "price":
return None
ws_symbol = msg.get("symbol")
try:
price = float(msg["price"])
except (KeyError, ValueError, TypeError) as e:
logger.warning(f"WebSocket: bad price data for {ws_symbol}: {e}")
return None
return ws_symbol, price
@staticmethod
async def _ws_heartbeat(ws) -> None:
"""Twelve Data drops idle WS connections; heartbeat every 10s keeps
it alive through quiet periods (weekends, low-liquidity hours)."""
while True:
await asyncio.sleep(10)
await ws.send(json.dumps({"action": "heartbeat"}))
async def iter_ticks(
self,
symbols: Sequence[str],
on_connect: Optional[Callable[[], None]] = None,
) -> AsyncIterator[Tuple[str, float]]:
"""One connection's lifetime of (canonical_symbol, price) ticks.
The TD WS speaks display symbols ("XAU/USD"); ticks are mapped back
to the canonical pair symbols passed in. The caller owns the
reconnect/backoff loop around this generator.
"""
import websockets
ws_to_pair = {PAIR_INFO[s]["display"]: s for s in symbols}
url = self.WS_URL.format(api_key=self._api_key or "")
async with websockets.connect(url) as ws:
subscribe = {
"action": "subscribe",
"params": {"symbols": ",".join(ws_to_pair)},
}
await ws.send(json.dumps(subscribe))
logger.info(f"WebSocket connected, subscribed to {len(ws_to_pair)} symbols")
if on_connect is not None:
on_connect()
hb_task = asyncio.create_task(self._ws_heartbeat(ws))
try:
async for raw in ws:
parsed = self._parse_ws_price(raw)
if parsed is None:
continue
pair_symbol = ws_to_pair.get(parsed[0])
if pair_symbol is None:
continue
yield pair_symbol, parsed[1]
finally:
hb_task.cancel()