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

1"""Concurrent multi-symbol price download.""" 

2 

3from __future__ import annotations 

4 

5import re 

6import warnings 

7from collections.abc import Iterable 

8from concurrent.futures import ThreadPoolExecutor 

9 

10import polars as pl 

11 

12from . import _chart, _http 

13from ._chart import DateLike 

14from ._ticker import Ticker 

15from .exceptions import YahooError 

16 

17 

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())) 

22 

23 

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 

36 

37 

38def _stack(frames: list[pl.DataFrame], interval: str) -> pl.DataFrame: 

39 """Stack per-symbol frames into one, sorted by ticker then time. 

40 

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)) 

51 

52 

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. 

69 

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. 

74 

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) 

87 

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 

95 

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)) 

99 

100 return _stack(_collect(symbols, outcomes, raise_errors), interval)