Coverage for src/polars_yahoo/_download.py: 100%
46 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"""Concurrent multi-symbol price download."""
3from __future__ import annotations
5import re
6import warnings
7from collections.abc import Iterable
8from concurrent.futures import ThreadPoolExecutor
10import polars as pl
12from . import _chart, _http
13from ._chart import DateLike
14from ._ticker import Ticker
15from .exceptions import YahooError
18def _normalise(tickers: str | Iterable[str]) -> list[str]:
19 """Split, upper-case and de-duplicate symbols, keeping their order."""
20 items = re.split(r"[\s,]+", tickers) if isinstance(tickers, str) else list(tickers)
21 return list(dict.fromkeys(s.strip().upper() for s in items if s and s.strip()))
24def _collect(symbols: list[str], outcomes: list[pl.DataFrame | YahooError], raise_errors: bool) -> list[pl.DataFrame]:
25 """Keep the frames that arrived; warn about (or raise) the failures."""
26 frames: list[pl.DataFrame] = []
27 for symbol, outcome in zip(symbols, outcomes, strict=True):
28 if isinstance(outcome, YahooError):
29 if raise_errors:
30 raise outcome
31 # stacklevel=3: attribute the warning to download()'s caller.
32 warnings.warn(f"skipping {symbol}: {outcome}", stacklevel=3)
33 else:
34 frames.append(outcome)
35 return frames
38def _stack(frames: list[pl.DataFrame], interval: str) -> pl.DataFrame:
39 """Stack per-symbol frames into one, sorted by ticker then time.
41 Intraday frames on different time zones are converted to UTC first, since a
42 polars column holds a single time zone.
43 """
44 if not frames:
45 return _chart.empty_prices(interval)
46 if _chart.is_intraday(interval):
47 zones = {dtype.time_zone for f in frames if isinstance(dtype := f.schema["timestamp"], pl.Datetime)}
48 if len(zones) > 1:
49 frames = [f.with_columns(pl.col("timestamp").dt.convert_time_zone("UTC")) for f in frames]
50 return pl.concat(frames, how="vertical").sort("ticker", _chart.time_column(interval))
53def download(
54 tickers: str | Iterable[str],
55 period: str | None = "1mo",
56 interval: str = "1d",
57 start: DateLike | None = None,
58 end: DateLike | None = None,
59 prepost: bool = False,
60 *,
61 max_workers: int = 8,
62 raise_errors: bool = False,
63 session: _http.Session | None = None,
64 timeout: float = _http.TIMEOUT,
65 retries: int = _http.RETRIES,
66 backoff: float = _http.BACKOFF,
67) -> pl.DataFrame:
68 """Download bars for several symbols into one long frame.
70 ``tickers`` is a list or a space/comma-separated string. The result has the
71 same columns as :meth:`Ticker.history`, stacked and sorted by ticker then
72 time. Intraday timestamps of symbols on different time zones are
73 converted to UTC so they can share one column.
75 A symbol that fails is skipped with a warning, or raised when
76 ``raise_errors`` is true. Passing ``session`` runs the requests one after
77 another, because a single session must not be shared across threads.
78 ``timeout``, ``retries`` and ``backoff`` apply to every request, as for
79 :class:`Ticker`.
80 """
81 symbols = _normalise(tickers)
82 if not symbols:
83 raise ValueError("no tickers given") # noqa: TRY003 - argument validation; a ValueError with context is the idiom
84 # Validate once, up front, so bad arguments fail before any request.
85 _chart.build_params(period=period, interval=interval, start=start, end=end, prepost=prepost)
86 _http.check_request_settings(timeout, retries, backoff)
88 def fetch(symbol: str) -> pl.DataFrame | YahooError:
89 """Fetch one symbol, returning the error instead of raising so other symbols still complete."""
90 try:
91 ticker = Ticker(symbol, session=session, timeout=timeout, retries=retries, backoff=backoff)
92 return ticker.history(period, interval, start, end, prepost)
93 except YahooError as exc:
94 return exc
96 workers = 1 if session is not None else max(1, min(max_workers, len(symbols)))
97 with ThreadPoolExecutor(max_workers=workers) as pool:
98 outcomes = list(pool.map(fetch, symbols))
100 return _stack(_collect(symbols, outcomes, raise_errors), interval)