Coverage for src/polars_yahoo/_chart.py: 100%

87 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 15:16 +0000

1"""Build chart-request parameters and turn chart responses into polars frames. 

2 

3Everything here is pure (no I/O) so it can be tested against recorded payloads. 

4""" 

5 

6from __future__ import annotations 

7 

8import datetime as dt 

9from typing import Any 

10 

11import polars as pl 

12 

13PERIODS = ("1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max") 

14INTRADAY_INTERVALS = ("1m", "2m", "5m", "15m", "60m", "90m", "1h") 

15DAILY_INTERVALS = ("1d", "5d", "1wk", "1mo", "3mo") 

16INTERVALS = INTRADAY_INTERVALS + DAILY_INTERVALS 

17 

18# For range=max Yahoo silently returns monthly bars whatever interval was asked 

19# for, so "max" is sent as an explicit window starting here (1900-01-01 UTC). 

20MAX_START = -2208988800 

21 

22PRICE_COLUMNS = ("open", "high", "low", "close", "adj_close") 

23 

24DateLike = dt.date | dt.datetime | str 

25 

26 

27def is_intraday(interval: str) -> bool: 

28 """Return True for minute/hour bars, which carry a timestamp rather than a date. 

29 

30 >>> is_intraday("5m"), is_intraday("1d") 

31 (True, False) 

32 """ 

33 return interval in INTRADAY_INTERVALS 

34 

35 

36def _to_epoch(value: DateLike) -> int: 

37 """Convert a date, datetime or ISO string to Unix seconds. 

38 

39 Naive values are taken as UTC; a bare date means midnight UTC. 

40 

41 >>> _to_epoch("2024-01-02") 

42 1704153600 

43 """ 

44 if isinstance(value, str): 

45 value = dt.datetime.fromisoformat(value) 

46 if not isinstance(value, dt.datetime): 

47 value = dt.datetime(value.year, value.month, value.day) 

48 if value.tzinfo is None: 

49 value = value.replace(tzinfo=dt.UTC) 

50 return int(value.timestamp()) 

51 

52 

53def _now() -> int: 

54 """Return the current time as Unix seconds.""" 

55 return int(dt.datetime.now(dt.UTC).timestamp()) 

56 

57 

58def _window(start: DateLike, end: DateLike | None) -> dict[str, int]: 

59 """Return an explicit ``period1``/``period2`` window; ``end`` defaults to now.""" 

60 period1 = _to_epoch(start) 

61 period2 = _to_epoch(end) if end is not None else _now() 

62 if period2 <= period1: 

63 raise ValueError("end must be after start") # noqa: TRY003 - argument validation; a ValueError with context is the idiom 

64 return {"period1": period1, "period2": period2} 

65 

66 

67def _period_range(period: str | None, interval: str, end: DateLike | None) -> dict[str, Any]: 

68 """Translate a named ``period`` into query parameters (used when no ``start`` is given).""" 

69 if end is not None: 

70 raise ValueError("end requires start") # noqa: TRY003 - argument validation; a ValueError with context is the idiom 

71 if period not in PERIODS: 

72 raise ValueError(f"period must be one of {', '.join(PERIODS)}, got {period!r}") # noqa: TRY003 - argument validation; a ValueError with context is the idiom 

73 if period != "max" or interval in ("1mo", "3mo"): 

74 return {"range": period} 

75 # For range=max Yahoo returns monthly bars, so send an explicit window instead. 

76 if is_intraday(interval): 

77 raise ValueError( # noqa: TRY003 - argument validation; a ValueError with context is the idiom 

78 f"period='max' is not available for intraday interval {interval!r}; " 

79 "Yahoo only keeps recent intraday bars, so pass a shorter period or a start" 

80 ) 

81 return {"period1": MAX_START, "period2": _now()} 

82 

83 

84def build_params( 

85 *, 

86 period: str | None = "1mo", 

87 interval: str = "1d", 

88 start: DateLike | None = None, 

89 end: DateLike | None = None, 

90 prepost: bool = False, 

91) -> dict[str, Any]: 

92 """Validate the arguments and translate them into chart query parameters. 

93 

94 Either ``period`` or ``start`` (optionally with ``end``) selects the range; 

95 ``start``/``end`` win, and ``end`` defaults to now. ``end`` is exclusive. 

96 

97 >>> build_params(period="5d")["range"] 

98 '5d' 

99 >>> params = build_params(period="max") # sent as an explicit window, not range=max 

100 >>> params["period1"], "range" in params 

101 (-2208988800, False) 

102 """ 

103 if interval not in INTERVALS: 

104 hint = " (Yahoo returns unreliable 30m bars; use 15m)" if interval == "30m" else "" 

105 raise ValueError(f"interval must be one of {', '.join(INTERVALS)}, got {interval!r}{hint}") # noqa: TRY003 - argument validation; a ValueError with context is the idiom 

106 

107 params: dict[str, Any] = { 

108 "interval": interval, 

109 "includePrePost": str(prepost).lower(), 

110 "events": "div,splits", 

111 "includeAdjustedClose": "true", 

112 } 

113 params.update(_window(start, end) if start is not None else _period_range(period, interval, end)) 

114 return params 

115 

116 

117def time_column(interval: str) -> str: 

118 """Name the time column a price frame for ``interval`` carries. 

119 

120 >>> time_column("5m"), time_column("1d") 

121 ('timestamp', 'date') 

122 """ 

123 return "timestamp" if is_intraday(interval) else "date" 

124 

125 

126def empty_prices(interval: str) -> pl.DataFrame: 

127 """Return an empty price frame for ``interval``, intraday timestamps in UTC. 

128 

129 >>> empty_prices("1d").columns 

130 ['ticker', 'date', 'open', 'high', 'low', 'close', 'adj_close', 'volume'] 

131 """ 

132 return pl.DataFrame(schema=_price_schema(is_intraday(interval), "UTC")) 

133 

134 

135def _price_schema(intraday: bool, tz: str) -> dict[str, pl.DataType]: 

136 """Return the price-frame schema: ``date`` for daily bars, a tz-aware ``timestamp`` for intraday.""" 

137 time_col: dict[str, pl.DataType] = ( 

138 {"timestamp": pl.Datetime("us", time_zone=tz)} if intraday else {"date": pl.Date()} 

139 ) 

140 return { 

141 "ticker": pl.String(), 

142 **time_col, 

143 **{c: pl.Float64() for c in PRICE_COLUMNS}, 

144 "volume": pl.Int64(), 

145 } 

146 

147 

148def _local_times(timestamps: list[int], tz: str) -> pl.Series: 

149 """Convert Unix seconds to microsecond datetimes in the exchange time zone.""" 

150 return ( 

151 pl.from_epoch(pl.Series("timestamp", timestamps, dtype=pl.Int64), time_unit="s") 

152 .cast(pl.Datetime("us")) 

153 .dt.replace_time_zone("UTC") 

154 .dt.convert_time_zone(tz) 

155 ) 

156 

157 

158def parse_prices(ticker: str, result: dict[str, Any], interval: str) -> pl.DataFrame: 

159 """Turn one chart ``result`` into a long price frame. 

160 

161 Columns: ``ticker``, then ``date`` (daily and longer bars, exchange-local 

162 calendar date) or ``timestamp`` (intraday, exchange time zone), then 

163 ``open, high, low, close, adj_close, volume``. ``adj_close`` is null for 

164 intraday bars because Yahoo does not provide it there. Rows with no prices 

165 at all are dropped, and for daily bars a duplicated trailing live bar is 

166 collapsed into one row per date. 

167 

168 >>> result = { 

169 ... "meta": {"exchangeTimezoneName": "America/New_York"}, 

170 ... "timestamp": [1704205800], 

171 ... "indicators": { 

172 ... "quote": [ 

173 ... {"open": [187.15], "high": [188.44], "low": [183.89], "close": [185.64], "volume": [82488700]} 

174 ... ], 

175 ... "adjclose": [{"adjclose": [184.73]}], 

176 ... }, 

177 ... } 

178 >>> frame = parse_prices("AAPL", result, "1d") 

179 >>> frame.columns 

180 ['ticker', 'date', 'open', 'high', 'low', 'close', 'adj_close', 'volume'] 

181 >>> frame.row(0) 

182 ('AAPL', datetime.date(2024, 1, 2), 187.15, 188.44, 183.89, 185.64, 184.73, 82488700) 

183 """ 

184 meta = result.get("meta") or {} 

185 tz = meta.get("exchangeTimezoneName") or "UTC" 

186 intraday = is_intraday(interval) 

187 schema = _price_schema(intraday, tz) 

188 

189 timestamps = result.get("timestamp") or [] 

190 if not timestamps: 

191 return pl.DataFrame(schema=schema) 

192 

193 indicators = result.get("indicators") or {} 

194 quote = (indicators.get("quote") or [{}])[0] 

195 adjclose = (indicators.get("adjclose") or [{}])[0].get("adjclose") 

196 n = len(timestamps) 

197 

198 def column(values: list[Any] | None) -> list[Any]: 

199 """Return ``values``, or a column of nulls when Yahoo omitted the field.""" 

200 return values if values is not None else [None] * n 

201 

202 frame = pl.DataFrame( 

203 { 

204 "ticker": [ticker] * n, 

205 "timestamp": _local_times(timestamps, tz), 

206 "open": column(quote.get("open")), 

207 "high": column(quote.get("high")), 

208 "low": column(quote.get("low")), 

209 "close": column(quote.get("close")), 

210 "adj_close": column(adjclose), 

211 "volume": column(quote.get("volume")), 

212 }, 

213 schema_overrides=dict.fromkeys(PRICE_COLUMNS, pl.Float64) | {"volume": pl.Int64}, 

214 ).filter(~pl.all_horizontal(pl.col("open", "high", "low", "close").is_null())) 

215 

216 if not intraday: 

217 frame = ( 

218 frame.with_columns(pl.col("timestamp").dt.date().alias("date")) 

219 .drop("timestamp") 

220 .unique(subset="date", keep="last", maintain_order=True) 

221 ) 

222 return frame.select(list(schema)).sort(time_column(interval)) 

223 

224 

225def parse_dividends(ticker: str, result: dict[str, Any]) -> pl.DataFrame: 

226 """Return ``ticker, date, dividend`` rows from a chart ``result``'s events. 

227 

228 >>> events = {"dividends": {"1715347800": {"date": 1715347800, "amount": 0.25}}} 

229 >>> parse_dividends("AAPL", {"meta": {"exchangeTimezoneName": "America/New_York"}, "events": events}).row(0) 

230 ('AAPL', datetime.date(2024, 5, 10), 0.25) 

231 """ 

232 tz = (result.get("meta") or {}).get("exchangeTimezoneName") or "UTC" 

233 events = list(((result.get("events") or {}).get("dividends") or {}).values()) 

234 schema = {"ticker": pl.String(), "date": pl.Date(), "dividend": pl.Float64()} 

235 if not events: 

236 return pl.DataFrame(schema=schema) 

237 return pl.DataFrame( 

238 { 

239 "ticker": [ticker] * len(events), 

240 "date": _local_times([e["date"] for e in events], tz).dt.date(), 

241 "dividend": [e.get("amount") for e in events], 

242 }, 

243 schema=schema, 

244 ).sort("date") 

245 

246 

247def parse_splits(ticker: str, result: dict[str, Any]) -> pl.DataFrame: 

248 """Return ``ticker, date, numerator, denominator, ratio`` rows from a chart ``result``. 

249 

250 >>> events = {"splits": {"1598880600": {"date": 1598880600, "numerator": 4, "denominator": 1}}} 

251 >>> parse_splits("AAPL", {"meta": {"exchangeTimezoneName": "America/New_York"}, "events": events}).row(0) 

252 ('AAPL', datetime.date(2020, 8, 31), 4.0, 1.0, 4.0) 

253 """ 

254 tz = (result.get("meta") or {}).get("exchangeTimezoneName") or "UTC" 

255 events = list(((result.get("events") or {}).get("splits") or {}).values()) 

256 schema = { 

257 "ticker": pl.String(), 

258 "date": pl.Date(), 

259 "numerator": pl.Float64(), 

260 "denominator": pl.Float64(), 

261 } 

262 if not events: 

263 return pl.DataFrame(schema=schema).with_columns(ratio=pl.lit(None, pl.Float64)) 

264 return ( 

265 pl.DataFrame( 

266 { 

267 "ticker": [ticker] * len(events), 

268 "date": _local_times([e["date"] for e in events], tz).dt.date(), 

269 "numerator": [e.get("numerator") for e in events], 

270 "denominator": [e.get("denominator") for e in events], 

271 }, 

272 schema=schema, 

273 ) 

274 .with_columns(ratio=pl.col("numerator") / pl.col("denominator")) 

275 .sort("date") 

276 )