downloader.resilience.download_combined_with_fallback

downloader.resilience.download_combined_with_fallback(
    api_key,
    *,
    start,
    end,
    now,
    max_retries,
    backoff,
    timeout,
    fallback_enabled,
    country_code='DE',
    sleep=_time_module.sleep,
)

Download the combined DE-total load series with snapshot fallback.

Single-series (“combined”) counterpart of download_with_fallback for scripts that target the aggregated DE-total endpoint (download_new_data) rather than the four per-zone CSVs. Reproduces the download_with_fallback function defined identically in chronos.py, team4_optuna_submit.py, and team4_spotoptim_submit.py.

Decision tree:

Seed the snapshot store from any existing interim/energy_load.csv.
Attempt download_new_data up to max_retries times, with exponential back-off backoff * 2**(attempt-1) between attempts.
On success: write a snapshot and return a DownloadResult with mode="combined" and combined_status="live".
On exhaustion: if fallback_enabled and a valid snapshot exists (within SNAPSHOT_TTL), restore it and return combined_status="cache"; otherwise return combined_status="missing" and mode=None.
Prune stale snapshots before returning.

The caller is responsible for raising / aborting on mode=None (unrecoverable).

Parameters

Name	Type	Description	Default
api_key	str	ENTSO-E Web API security token.	required
start	str	Download start in `"YYYYMMDDHHMM"` format.	required
end	str	Download end in `"YYYYMMDDHHMM"` format.	required
now	pd.Timestamp	Current UTC timestamp (used for snapshot naming and TTL checks).	required
max_retries	int	Total number of download attempts.	required
backoff	float	Base wait in seconds between attempts (exponential: `backoff * 2**(attempt-1)`).	required
timeout	float \| None	Per-socket read timeout in seconds, or `None` to disable.	required
fallback_enabled	bool	When `False`, cached snapshots are never READ as a fallback (live data or `"missing"`), but they are still written on success.	required
country_code	str	ENTSO-E country code passed to `download_new_data`. Defaults to `"DE"`.	`'DE'`
sleep	Callable[[float], None]	Callable used for inter-attempt waits; injected so tests can pass `sleep=lambda s: None` for instant execution.	`_time_module.sleep`

Returns

Name	Type	Description
DownloadResult	DownloadResult	`mode="combined"` on success (live or cache),
	DownloadResult	`mode=None` when unrecoverable. `zones` is always an empty dict
	DownloadResult	(no per-zone download is attempted). `fallback_gate` is `True`
	DownloadResult	when `combined_status="cache"`.

Examples

import pandas as pd
from spotforecast2_safe.downloader import resilience as resil

result = resil.download_combined_with_fallback(
    api_key="YOUR_API_KEY",
    start="202301010000",
    end="202301050000",
    now=pd.Timestamp.now(tz="UTC"),
    max_retries=3,
    backoff=5.0,
    timeout=60.0,
    fallback_enabled=True,
)
if result.mode is None:
    raise SystemExit("unrecoverable: no live data and no valid snapshot")
print(result.report())