Skip to content

release: 22.6.0 — ENTSO-E gap repair + resume/cooldown fixes #383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bartzbeielstein merged 4 commits into from
Jun 13, 2026
Merged

release: 22.6.0 — ENTSO-E gap repair + resume/cooldown fixes #383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1d4f4ad
chore: sync main into develop [skip ci]
github-actions[bot] Jun 13, 2026
848027f
feat(downloader): ENTSO-E gap repair + resume/cooldown fixes; default…
bartzbeielstein Jun 13, 2026
a2fd985
Merge pull request #382 from sequential-parameter-optimization/feat/e…
bartzbeielstein Jun 13, 2026
b8fae59
chore(release): 22.6.0-rc.1 [skip ci]
semantic-release-bot Jun 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
## [22.6.0-rc.1](https://github.com/sequential-parameter-optimization/spotforecast2-safe/compare/v22.5.0...v22.6.0-rc.1) (2026-06-13)


### Features

* **downloader:** ENTSO-E gap repair + resume/cooldown fixes; default country_code DE ([848027f](https://github.com/sequential-parameter-optimization/spotforecast2-safe/commit/848027fa7be0ee072bf6fd976a2016e61f4c41d6))

## [22.5.0](https://github.com/sequential-parameter-optimization/spotforecast2-safe/compare/v22.4.1...v22.5.0) (2026-06-13)


Expand Down
8 changes: 4 additions & 4 deletions MODEL_CARD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This card describes what spotforecast2-safe is, how to use it safely, the condit
| Field | Value |
| --- | --- |
| Name | spotforecast2-safe |
| Version | 22.5.0 |
| Version | 22.6.0-rc.1 |
| Type | Deterministic Python library for time series feature engineering and recursive multi-step forecasting. It performs no training of its own. |
| Developed by | Thomas Bartz-Beielstein, ORCID [0000-0002-5938-5158](https://orcid.org/0000-0002-5938-5158) |
| Distributed by | the `sequential-parameter-optimization` GitHub organization |
Expand All @@ -18,7 +18,7 @@ This card describes what spotforecast2-safe is, how to use it safely, the condit

The library depends only on numpy, pandas, scikit-learn, lightgbm, numba, pyarrow, requests, feature-engine, holidays, astral, and tqdm. It deliberately excludes plotly, matplotlib, spotoptim, optuna, torch, and tensorflow, so no plotting or automated-tuning code ships in this package.

Two Common Platform Enumeration (CPE) identifiers let vulnerability-tracking and software bill of materials (SBOM) tools recognize the package. The wildcard identifier `cpe:2.3:a:sequential_parameter_optimization:spotforecast2_safe:*:*:*:*:*:*:*:*` matches any release; the current release is `cpe:2.3:a:sequential_parameter_optimization:spotforecast2_safe:22.5.0:*:*:*:*:*:*:*`.
Two Common Platform Enumeration (CPE) identifiers let vulnerability-tracking and software bill of materials (SBOM) tools recognize the package. The wildcard identifier `cpe:2.3:a:sequential_parameter_optimization:spotforecast2_safe:*:*:*:*:*:*:*:*` matches any release; the current release is `cpe:2.3:a:sequential_parameter_optimization:spotforecast2_safe:22.6.0-rc.1:*:*:*:*:*:*:*`.

The library itself is a low-risk component: it is deterministic, its source is fully inspectable, and it fails safe on invalid input. It is built to support high-risk AI systems in the sense of the EU AI Act, but it is not itself such a system. When it is embedded in a high-risk deployment, the duties that attach to that system fall on the integrator, not on the library.

Expand All @@ -30,7 +30,7 @@ Responsibilities are divided as follows.
| Distribution | sequential-parameter-optimization on GitHub | repository issue tracker |
| Deployment, operation, and audit | the system integrator | defined per deployment |

The current release is 22.5.0, with a stable public interface pinned in `spotforecast2_safe.__init__.__all__`. The full version history, including release dates, is recorded in `CHANGELOG.md` and on the GitHub Releases page; it is maintained automatically by the release pipeline and is not repeated here.
The current release is 22.6.0-rc.1, with a stable public interface pinned in `spotforecast2_safe.__init__.__all__`. The full version history, including release dates, is recorded in `CHANGELOG.md` and on the GitHub Releases page; it is maintained automatically by the release pipeline and is not repeated here.

## 2. Intended Use and Scope

Expand Down Expand Up @@ -216,7 +216,7 @@ Maintainer: Thomas Bartz-Beielstein, ORCID [0000-0002-5938-5158](https://orcid.o
}
```

Or as a formatted reference: Bartz-Beielstein, T. (2026). *spotforecast2-safe: Safety-critical subset of spotforecast2* (Version 22.5.0) [Computer software]. https://github.com/sequential-parameter-optimization/spotforecast2-safe
Or as a formatted reference: Bartz-Beielstein, T. (2026). *spotforecast2-safe: Safety-critical subset of spotforecast2* (Version 22.6.0-rc.1) [Computer software]. https://github.com/sequential-parameter-optimization/spotforecast2-safe

The technical report (`bart26h/index.qmd`) is the long-form reference for design rationale, compliance mapping, and evaluation protocol.

Expand Down
6 changes: 6 additions & 0 deletions _quarto.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -445,6 +445,10 @@ website:
file: docs/reference/downloader.entsoe.download_day_ahead_price.qmd
- text: "merge_build_manual"
file: docs/reference/downloader.entsoe.merge_build_manual.qmd
- text: "repair_data_gaps"
file: docs/reference/downloader.entsoe.repair_data_gaps.qmd
- text: "find_missing_intervals"
file: docs/reference/downloader.entsoe.find_missing_intervals.qmd
- text: "download_zone_loads"
file: docs/reference/downloader.entsoe.download_zone_loads.qmd
- text: "assemble_zone_loads"
Expand Down Expand Up @@ -832,6 +836,8 @@ quartodoc:
- downloader.entsoe.download_renewable_forecast
- downloader.entsoe.download_day_ahead_price
- downloader.entsoe.merge_build_manual
- downloader.entsoe.repair_data_gaps
- downloader.entsoe.find_missing_intervals
- downloader.entsoe.download_zone_loads
- downloader.entsoe.assemble_zone_loads
- downloader.entsoe.ZoneResult
Expand Down
34 changes: 18 additions & 16 deletions docs/reference/downloader.entsoe.download_new_data.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,13 @@
```python
downloader.entsoe.download_new_data(
api_key,
country_code='FR',
country_code='DE',
start=None,
end=None,
force=False,
keep_forecast_future=False,
timeout=60.0,
on_unavailable='raise',
)
```

Expand All @@ -25,23 +26,24 @@ automatically on the next incremental download.

## Parameters {.doc-section .doc-section-parameters}

| Name | Type | Description | Default |
|----------------------|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| api_key | [str](`str`) | The ENTSO-E API key. | _required_ |
| country_code | [str](`str`) | The country code to query (e.g., 'FR', 'DE'). Defaults to "FR". | `'FR'` |
| start | [str](`str`) \| None | Start date in 'YYYYMMDDHH00' format. | `None` |
| end | [str](`str`) \| None | End date in 'YYYYMMDDHH00' format. | `None` |
| force | [bool](`bool`) | If True, bypass the 24h cooldown check. | `False` |
| keep_forecast_future | [bool](`bool`) | If True, retain rows after the current UTC moment when building the interim file, preserving ENTSO-E's day-ahead `Forecasted Load` for tomorrow. Defaults to False (future rows are dropped, the leakage-free input for training). The flag only keeps rows the query window already covers, so pass an ``end`` that reaches into the target day (e.g. tomorrow) as well. See `merge_build_manual` for details. | `False` |
| timeout | [Optional](`typing.Optional`)\[[float](`float`)\] | Per-socket-operation read timeout in seconds passed to the ENTSO-E client. Kills stalled connections (raises ``requests.exceptions.Timeout``, caught by the existing retry loop, then ``RuntimeError`` after retries) without bounding long live transfers. ``None`` disables the timeout. Defaults to ``60.0``. | `60.0` |
| Name | Type | Description | Default |
|----------------------|------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| api_key | [str](`str`) | The ENTSO-E API key. | _required_ |
| country_code | [str](`str`) | The country code to query (e.g., 'DE', 'FR'). Defaults to "DE". | `'DE'` |
| start | [str](`str`) \| [pd](`pandas`).[Timestamp](`pandas.Timestamp`) \| None | Start of the query window ('YYYYMMDDHH00' or a timestamp). If None, resumes from the last observed timestamp in the interim file, extending back to heal still-missing actuals (bounded by ``_MAX_BACKFILL_DAYS``) and falling back to seven days ago when no prior data exists. | `None` |
| end | [str](`str`) \| [pd](`pandas`).[Timestamp](`pandas.Timestamp`) \| None | End of the query window ('YYYYMMDDHH00' or a timestamp). If None, the current UTC moment is used. | `None` |
| force | [bool](`bool`) | If True, bypass the cooldown that skips a download when the last successful download is younger than ``_COOLDOWN_HOURS`` (24) hours. The cooldown is bypassed automatically when the requested window overlaps a known gap in the interim data, so gap backfills are never silently skipped. | `False` |
| keep_forecast_future | [bool](`bool`) | If True, retain rows after the current UTC moment when building the interim file, preserving ENTSO-E's day-ahead `Forecasted Load` for tomorrow. Defaults to False (future rows are dropped, the leakage-free input for training). The flag only keeps rows the query window already covers, so pass an ``end`` that reaches into the target day (e.g. tomorrow) as well. See `merge_build_manual` for details. | `False` |
| timeout | [Optional](`typing.Optional`)\[[float](`float`)\] | Per-socket-operation read timeout in seconds passed to the ENTSO-E client. Kills stalled connections (raises ``requests.exceptions.Timeout``, caught by the existing retry loop, then ``RuntimeError`` after retries) without bounding long live transfers. ``None`` disables the timeout. Defaults to ``60.0``. | `60.0` |
| on_unavailable | [OnUnavailable](`spotforecast2_safe.downloader.entsoe.OnUnavailable`) | What to do when ENTSO-E stays unreachable after the retry budget is exhausted. ``"raise"`` (default) raises ``RuntimeError``; ``"use_existing"`` logs how stale the interim data is and returns so the caller can continue on existing data (requires an existing interim file, else ``RuntimeError``). | `'raise'` |

## Raises {.doc-section .doc-section-raises}

| Name | Type | Description |
|--------|--------------------------------|----------------------------------------------------------------|
| | [ImportError](`ImportError`) | If the Python package 'entsoe-py' is not installed. |
| | [ValueError](`ValueError`) | If ``start`` or ``end`` cannot be parsed as a valid timestamp. |
| | [RuntimeError](`RuntimeError`) | If data fetching fails after ``_MAX_RETRIES`` attempts. |
| Name | Type | Description |
|--------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | [ImportError](`ImportError`) | If the Python package 'entsoe-py' is not installed. |
| | [ValueError](`ValueError`) | If ``start`` or ``end`` cannot be parsed as a valid timestamp, if both are given explicitly but ``end`` is not after ``start``, or if ``on_unavailable`` is not a recognized value. |
| | [RuntimeError](`RuntimeError`) | If data fetching fails after ``_MAX_RETRIES`` attempts and ``on_unavailable='raise'``. |

## Notes {.doc-section .doc-section-notes}

Expand Down Expand Up @@ -79,7 +81,7 @@ download_new_data(
)

# Incremental download (automatically resumes from last data point)
download_new_data(api_key="YOUR_API_KEY", country_code="FR")
download_new_data(api_key="YOUR_API_KEY", country_code="DE")

# Forced download bypassing the 24-hour cooldown check
download_new_data(
Expand Down
Loading