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
« 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.
3Everything here is pure (no I/O) so it can be tested against recorded payloads.
4"""
6from __future__ import annotations
8import datetime as dt
9from typing import Any
11import polars as pl
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
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
22PRICE_COLUMNS = ("open", "high", "low", "close", "adj_close")
24DateLike = dt.date | dt.datetime | str
27def is_intraday(interval: str) -> bool:
28 """Return True for minute/hour bars, which carry a timestamp rather than a date.
30 >>> is_intraday("5m"), is_intraday("1d")
31 (True, False)
32 """
33 return interval in INTRADAY_INTERVALS
36def _to_epoch(value: DateLike) -> int:
37 """Convert a date, datetime or ISO string to Unix seconds.
39 Naive values are taken as UTC; a bare date means midnight UTC.
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())
53def _now() -> int:
54 """Return the current time as Unix seconds."""
55 return int(dt.datetime.now(dt.UTC).timestamp())
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}
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()}
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.
94 Either ``period`` or ``start`` (optionally with ``end``) selects the range;
95 ``start``/``end`` win, and ``end`` defaults to now. ``end`` is exclusive.
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
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
117def time_column(interval: str) -> str:
118 """Name the time column a price frame for ``interval`` carries.
120 >>> time_column("5m"), time_column("1d")
121 ('timestamp', 'date')
122 """
123 return "timestamp" if is_intraday(interval) else "date"
126def empty_prices(interval: str) -> pl.DataFrame:
127 """Return an empty price frame for ``interval``, intraday timestamps in UTC.
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"))
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 }
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 )
158def parse_prices(ticker: str, result: dict[str, Any], interval: str) -> pl.DataFrame:
159 """Turn one chart ``result`` into a long price frame.
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.
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)
189 timestamps = result.get("timestamp") or []
190 if not timestamps:
191 return pl.DataFrame(schema=schema)
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)
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
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()))
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))
225def parse_dividends(ticker: str, result: dict[str, Any]) -> pl.DataFrame:
226 """Return ``ticker, date, dividend`` rows from a chart ``result``'s events.
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")
247def parse_splits(ticker: str, result: dict[str, Any]) -> pl.DataFrame:
248 """Return ``ticker, date, numerator, denominator, ratio`` rows from a chart ``result``.
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 )