pse-opendata 0.2.0__tar.gz

pse_opendata-0.2.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [semantic versioning](https://semver.org/).
+
+## [0.2.0] - 2026-10-30
+
+First release on PyPI.
+
+### Added
+
+- `Client.loads`: one `MonthLoad` per month loaded (cached, downloaded or stale, with the download time and the
+  number of rows), e.g. to show data freshness on a dashboard.
+- `CITATION.cff` and Zenodo metadata.
+
+### Changed
+
+- Installation from PyPI (`pip install pse-opendata`) in the README and the documentation.
+
+## [0.1.0] - 2026-10-26
+
+First version, published on GitHub only (commit 8b01ec8), not on PyPI.
+
+### Added
+
+- `get(report, start, end)` for 16 reports of the PSE reports API (prices, balancing market, power system), returning
+  frames with `start_utc`, `end_utc`, `start_local`, `end_local` and `business_date` on every row.
+- Convenience functions `rce`, `sdac`, `fundamentals`, `imbalance_prices` and `balancing_capacity`.
+- Report catalogue with titles, field descriptions, units, resolution, first date, revision window and PSE sources,
+  checked on 2026-10-26; unconfirmed units are marked unverified.
+- Legacy CSV export of www.pse.pl (`legacy`): `PL_WYK_KSE`, `PL_GEN_WIATR`, `PL_CENY_RYN_EN`, `PL_CENY_ROZL_RB`,
+  hourly until 2024-06-13, with DST hour labels, changing columns and rate limits handled.
+- `history` for hourly `rce`, `demand`, `wind` and `pv` series stitched across the switch to the API on 2024-06-14,
+  with optional rescaling (`splice_factor`).
+- Monthly Parquet cache with per-report revision windows, offline and stale modes; retries with backoff, request
+  spacing, explicit exceptions and logging.
+- Day-by-day single-page requests for `popmb-rmb`, whose keyset paging skips rows.
+- Command line interface `pse-opendata` (`get`, `legacy`, `history`, `reports`, `cache`).
+- Offline tests on recorded PSE responses, optional live tests, ruff, mypy, GitHub Actions for Python 3.11-3.13,
+  MkDocs documentation and a release workflow for PyPI Trusted Publishing (disabled).
+
+[0.2.0]: https://github.com/kwwaleszczynski-del/pse-opendata/releases/tag/v0.2.0
+[0.1.0]: https://github.com/kwwaleszczynski-del/pse-opendata/tree/8b01ec882b6f3af9c9ea91308293dda64108d705

pse_opendata-0.2.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+type: software
+title: "pse-opendata: Python client for the public data of PSE, the Polish transmission system operator"
+abstract: >-
+  An unofficial Python client for the public data of PSE S.A., the Polish transmission system operator: the
+  reports API (market prices RCE and SDAC, demand and generation, the balancing market, cross-border flows and
+  redispatch of renewables) and the legacy CSV export with the history before June 2024. It returns tidy pandas
+  frames with explicit interval start and end times in UTC and Polish local time, caches monthly Parquet files
+  with per-report revision windows and handles the pitfalls of the sources: interval-end time stamps, daylight
+  saving days, hourly products repeated in quarter-hours, republished settlement data, rate limits and keyset
+  paging that skips repeated balancing capacity offers. Not affiliated with PSE S.A.
+authors:
+  - family-names: "Waleszczyński"
+    given-names: "Konrad"
+version: 0.2.0
+date-released: "2026-10-30"
+license: MIT
+repository-code: "https://github.com/kwwaleszczynski-del/pse-opendata"
+url: "https://kwwaleszczynski-del.github.io/pse-opendata/"
+keywords:
+  - electricity market
+  - power system
+  - open data
+  - Poland
+  - PSE
+  - transmission system operator
+  - balancing market
+  - day-ahead prices
+  - renewable energy
+  - pandas

pse_opendata-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konrad Waleszczyński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pse_opendata-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+include CITATION.cff
+recursive-include tests *.py *.json *.csv *.md

pse_opendata-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: pse-opendata
+Version: 0.2.0
+Summary: Unofficial Python client for the public data of PSE, the Polish transmission system operator: reports API and legacy CSV export, as tidy pandas frames with explicit interval times.
+Author: Konrad Waleszczyński
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kwwaleszczynski-del/pse-opendata
+Project-URL: Documentation, https://kwwaleszczynski-del.github.io/pse-opendata/
+Project-URL: Changelog, https://github.com/kwwaleszczynski-del/pse-opendata/blob/main/CHANGELOG.md
+Keywords: pse,poland,electricity,power-system,energy-market,rce,balancing-market,open-data,pandas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.1
+Requires-Dist: pyarrow>=14
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
+Dynamic: license-file
+
+# pse-opendata
+
+[![tests](https://github.com/kwwaleszczynski-del/pse-opendata/actions/workflows/ci.yml/badge.svg)](https://github.com/kwwaleszczynski-del/pse-opendata/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://kwwaleszczynski-del.github.io/pse-opendata/)
+[![PyPI](https://img.shields.io/pypi/v/pse-opendata.svg)](https://pypi.org/project/pse-opendata/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Unofficial Python client for the public data of **PSE S.A.**, the Polish transmission system operator: market
+prices (RCE, SDAC), demand and generation, the balancing market (imbalance prices, balancing capacity, offers),
+cross-border flows and redispatch of renewables. It returns tidy `pandas` frames with explicit interval start and
+end times in UTC and Polish local time, caches monthly Parquet files and also reads the legacy CSV export that holds
+the history before June 2024.
+
+> This is an independent open-source project. It is not affiliated with, endorsed by or supported by PSE S.A.
+
+## Why
+
+PSE publishes its data openly at [api.raporty.pse.pl](https://api.raporty.pse.pl) (from 14 June 2024) and, for
+earlier years, through the CSV export of [www.pse.pl](https://www.pse.pl/raporty-historyczne). Both are easy to
+download and easy to get subtly wrong:
+
+- `dtime_utc` is the **end** of each interval, not the start; local `dtime` reads `02a:15` on the autumn DST day;
+- the API pages with `$first` and `nextLink`, at most 100,000 rows per page, and its keyset paging **skips rows**
+  of the balancing capacity offers (`popmb-rmb`) at page boundaries;
+- RCE and SDAC were hourly products until 30 September 2025: the API repeats the hourly price in four quarter-hours;
+- settlement reports are republished for months after the fact (imbalance volumes up to ~230 days later);
+- the legacy export is slow, rate-limited, takes one month per request, labels the extra autumn hour `2A`, changes
+  its columns over the years and does not overlap with the API, whose demand sits ~0.7% below it at the switch.
+
+`pse-opendata` handles these once, with tests on recorded responses, instead of a copy of a small client in every
+analysis project. Details: [time and data pitfalls](https://kwwaleszczynski-del.github.io/pse-opendata/pitfalls/).
+
+## Install
+
+Python 3.11 or newer:
+
+```bash
+pip install pse-opendata
+```
+
+## Quick start
+
+```python
+import pse_opendata as pse
+
+rce = pse.rce("2025-01-01", "2025-01-31")                    # RCE price, PLN/MWh, 15-minute rows
+mix = pse.fundamentals("2025-06-01", "2025-06-30", fields=["demand", "wi", "pv"])   # MW
+cen = pse.imbalance_prices("2025-07-01", "2025-07-31")       # imbalance price CEN and balancing energy prices
+cap = pse.balancing_capacity("2025-07-01", "2025-07-31")     # FCR/aFRR/mFRRd/RR prices and MW, hourly
+sdac = pse.get("csdac-pln", "2025-10-01", "2025-10-07")      # any catalogued report by name
+
+demand = pse.history("demand", "2024-01-01", "2024-12-31")   # legacy export + API, hourly, one series
+```
+
+Every frame has the same time columns, one row per interval:
+
+| column | meaning |
+|---|---|
+| `start_utc`, `end_utc` | interval start and end, `datetime64[ns, UTC]` |
+| `start_local`, `end_local` | the same instants in `Europe/Warsaw` (DST days are unambiguous) |
+| `business_date` | trading day in Polish local time (`datetime.date`) |
+
+followed by row keys (for reports with several rows per interval) and the fields of the report, with PSE's field
+names (e.g. `rce_pln`, `demand`, `wi`, `pv`, `cen_cost`). Dates are business days, inclusive.
+
+From the command line:
+
+```bash
+pse-opendata get rce-pln --start 2025-01-01 --end 2025-01-31 --out rce.parquet
+pse-opendata get his-wlk-cal --start 2025-06-01 --fields demand,wi,pv --out mix.csv
+pse-opendata history demand --start 2024-01-01 --end 2024-12-31 --out demand.parquet
+pse-opendata reports
+```
+
+## Catalogue
+
+| Report | Content | Resolution | From |
+|---|---|---|---|
+| `rce-pln` | RCE, market price of electricity | 15 min (hourly product until 2025-09-30) | 2024-06-14 |
+| `csdac-pln` | SDAC day-ahead price for Poland | 15 min (hourly product until 2025-09-30) | 2024-06-14 |
+| `crb-rozl` | Imbalance price CEN and balancing energy prices | 15 min | 2024-06-14 |
+| `en-rozl` | Imbalance energy volumes | 15 min | 2024-06-14 |
+| `eb-rozl` | Activated balancing energy, incl. aFRR platform | 15 min | 2024-06-14 |
+| `cmbp-tp`, `mbp-tp` | Balancing capacity prices and volumes, primary procurement | 1 h | 2024-06-14 |
+| `cmbu-tu`, `mbu-tu` | Balancing capacity prices and volumes, supplementary procurement | 15 min | 2024-06-14 |
+| `popmb-rmb` | Anonymous portfolio offers for balancing capacity | 1 h, many rows | 2024-06-14 |
+| `his-wlk-cal` | Demand, generation by unit type, wind, PV, exchange | 15 min | 2024-06-14 |
+| `kse-load` | Forecast and actual load | 15 min | 2024-06-14 |
+| `pdgopkd` | Day-ahead coordinated plan (forecast demand, wind, PV, reserves) | 15 min | 2024-06-14 |
+| `poze-redoze` | Non-market redispatch of wind and PV | 15 min | 2024-09-24 |
+| `przeplywy-mocy` | Physical cross-border flows per section | 15 min, many rows | 2024-06-14 |
+| `gen-jw` | Generation per unit (≥ 100 MW) | 15 min, many rows | 2024-06-14 |
+
+Legacy export (hourly, until 2024-06-13): `PL_WYK_KSE` (demand, JWCD/nJWCD generation, exchange, from 2009),
+`PL_GEN_WIATR` (wind from 2012-05-26, PV from 2020-04-10), `PL_CENY_RYN_EN` (RCE, from 2018),
+`PL_CENY_ROZL_RB` (imbalance prices CRO of the old balancing market, from 2009). The legacy server is slow (about a
+minute per month, one month per request), so long histories take a while the first time and are then cached.
+Field descriptions, units, sources and notes for each report:
+[report catalogue](https://kwwaleszczynski-del.github.io/pse-opendata/reports/). Other endpoints of the API can
+be read raw with `pse.Client().records(endpoint, filter=...)`.
+
+## Cache and reliability
+
+- Whole months are cached as Parquet files (`$PSE_OPENDATA_CACHE` or the user cache directory; `Client(cache_dir=...)`
+  to choose, `cache_dir=None` to switch off). A month is reused only once it was downloaded after the report's
+  revision window (3 days for prices, up to 240 days for settlement volumes); the legacy history never changes.
+- Requests retry with exponential backoff on network errors, HTTP 429 and 5xx (honouring `Retry-After`) and are
+  spaced (0.2 s for the API, 15 s for the legacy export).
+- `offline=True` reads the cache only; `allow_stale=True` falls back to a cached copy when a download fails.
+- Errors are explicit: `PseApiError` (with the API's message), `UnknownReportError`, `UnknownFieldError`,
+  `CacheMissError`, `LegacyFormatError`. Logging goes to the `pse_opendata` logger.
+
+## Data source and terms of use
+
+All data come from public reports of **PSE S.A.** (Polskie Sieci Elektroenergetyczne): the reports API
+`https://api.raporty.pse.pl/api` and the export of www.pse.pl. No key is needed. This package does not include or
+redistribute PSE data, except small samples of real responses used as test fixtures (see
+[tests/fixtures/README.md](tests/fixtures/README.md)).
+
+PSE publishes conditions for re-using public sector information
+([BIP, "Ponowne wykorzystywanie informacji sektora publicznego"](https://www.pse.pl/bip/ponowne-wykorzystanie-informacji-publicznej),
+entry changed on 14 October 2026, checked on 26 October 2026). They allow commercial and non-commercial re-use of
+information published in the BIP and on www.pse.pl free of charge, on condition that you name the source and the date
+the information was obtained (e.g. "Informacja pozyskana od PSE S.A. według stanu strony www.pse.pl na dzień
+[data]"), remove the PSE logo, keep unchanged information unchanged and, when you pass on processed information, tell
+recipients that it was changed and how, without misleading them. PSE accepts no liability for processed information,
+and some materials may be protected by copyright or database rights. The conditions are written for www.pse.pl;
+the reports API is run by the same operator. When you publish results built with this package, add the attribution
+yourself, for example:
+
+> Information obtained from www.pse.pl (PSE S.A. report `rce-pln`), state as of [date]. The information has been
+> processed in whole or in part.
+
+## Documentation and development
+
+Documentation: <https://kwwaleszczynski-del.github.io/pse-opendata/> (installation, examples, catalogue, time
+pitfalls, API reference). To work on the package:
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev,docs]"     # Linux/macOS: .venv/bin/python
+pytest -q                                                 # offline, recorded responses
+pytest -q --live tests/live                               # optional: calls the real PSE servers
+ruff check .
+mypy
+mkdocs build --strict
+```
+
+## Citation
+
+If you use the package in published work, please cite it; see [`CITATION.cff`](CITATION.cff).
+
+## License
+
+Code: MIT, see [LICENSE](LICENSE). Data: PSE S.A. public reports, see
+[Data source and terms of use](#data-source-and-terms-of-use).

pse_opendata-0.2.0/README.md

@@ -0,0 +1,156 @@
+# pse-opendata
+
+[![tests](https://github.com/kwwaleszczynski-del/pse-opendata/actions/workflows/ci.yml/badge.svg)](https://github.com/kwwaleszczynski-del/pse-opendata/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://kwwaleszczynski-del.github.io/pse-opendata/)
+[![PyPI](https://img.shields.io/pypi/v/pse-opendata.svg)](https://pypi.org/project/pse-opendata/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Unofficial Python client for the public data of **PSE S.A.**, the Polish transmission system operator: market
+prices (RCE, SDAC), demand and generation, the balancing market (imbalance prices, balancing capacity, offers),
+cross-border flows and redispatch of renewables. It returns tidy `pandas` frames with explicit interval start and
+end times in UTC and Polish local time, caches monthly Parquet files and also reads the legacy CSV export that holds
+the history before June 2024.
+
+> This is an independent open-source project. It is not affiliated with, endorsed by or supported by PSE S.A.
+
+## Why
+
+PSE publishes its data openly at [api.raporty.pse.pl](https://api.raporty.pse.pl) (from 14 June 2024) and, for
+earlier years, through the CSV export of [www.pse.pl](https://www.pse.pl/raporty-historyczne). Both are easy to
+download and easy to get subtly wrong:
+
+- `dtime_utc` is the **end** of each interval, not the start; local `dtime` reads `02a:15` on the autumn DST day;
+- the API pages with `$first` and `nextLink`, at most 100,000 rows per page, and its keyset paging **skips rows**
+  of the balancing capacity offers (`popmb-rmb`) at page boundaries;
+- RCE and SDAC were hourly products until 30 September 2025: the API repeats the hourly price in four quarter-hours;
+- settlement reports are republished for months after the fact (imbalance volumes up to ~230 days later);
+- the legacy export is slow, rate-limited, takes one month per request, labels the extra autumn hour `2A`, changes
+  its columns over the years and does not overlap with the API, whose demand sits ~0.7% below it at the switch.
+
+`pse-opendata` handles these once, with tests on recorded responses, instead of a copy of a small client in every
+analysis project. Details: [time and data pitfalls](https://kwwaleszczynski-del.github.io/pse-opendata/pitfalls/).
+
+## Install
+
+Python 3.11 or newer:
+
+```bash
+pip install pse-opendata
+```
+
+## Quick start
+
+```python
+import pse_opendata as pse
+
+rce = pse.rce("2025-01-01", "2025-01-31")                    # RCE price, PLN/MWh, 15-minute rows
+mix = pse.fundamentals("2025-06-01", "2025-06-30", fields=["demand", "wi", "pv"])   # MW
+cen = pse.imbalance_prices("2025-07-01", "2025-07-31")       # imbalance price CEN and balancing energy prices
+cap = pse.balancing_capacity("2025-07-01", "2025-07-31")     # FCR/aFRR/mFRRd/RR prices and MW, hourly
+sdac = pse.get("csdac-pln", "2025-10-01", "2025-10-07")      # any catalogued report by name
+
+demand = pse.history("demand", "2024-01-01", "2024-12-31")   # legacy export + API, hourly, one series
+```
+
+Every frame has the same time columns, one row per interval:
+
+| column | meaning |
+|---|---|
+| `start_utc`, `end_utc` | interval start and end, `datetime64[ns, UTC]` |
+| `start_local`, `end_local` | the same instants in `Europe/Warsaw` (DST days are unambiguous) |
+| `business_date` | trading day in Polish local time (`datetime.date`) |
+
+followed by row keys (for reports with several rows per interval) and the fields of the report, with PSE's field
+names (e.g. `rce_pln`, `demand`, `wi`, `pv`, `cen_cost`). Dates are business days, inclusive.
+
+From the command line:
+
+```bash
+pse-opendata get rce-pln --start 2025-01-01 --end 2025-01-31 --out rce.parquet
+pse-opendata get his-wlk-cal --start 2025-06-01 --fields demand,wi,pv --out mix.csv
+pse-opendata history demand --start 2024-01-01 --end 2024-12-31 --out demand.parquet
+pse-opendata reports
+```
+
+## Catalogue
+
+| Report | Content | Resolution | From |
+|---|---|---|---|
+| `rce-pln` | RCE, market price of electricity | 15 min (hourly product until 2025-09-30) | 2024-06-14 |
+| `csdac-pln` | SDAC day-ahead price for Poland | 15 min (hourly product until 2025-09-30) | 2024-06-14 |
+| `crb-rozl` | Imbalance price CEN and balancing energy prices | 15 min | 2024-06-14 |
+| `en-rozl` | Imbalance energy volumes | 15 min | 2024-06-14 |
+| `eb-rozl` | Activated balancing energy, incl. aFRR platform | 15 min | 2024-06-14 |
+| `cmbp-tp`, `mbp-tp` | Balancing capacity prices and volumes, primary procurement | 1 h | 2024-06-14 |
+| `cmbu-tu`, `mbu-tu` | Balancing capacity prices and volumes, supplementary procurement | 15 min | 2024-06-14 |
+| `popmb-rmb` | Anonymous portfolio offers for balancing capacity | 1 h, many rows | 2024-06-14 |
+| `his-wlk-cal` | Demand, generation by unit type, wind, PV, exchange | 15 min | 2024-06-14 |
+| `kse-load` | Forecast and actual load | 15 min | 2024-06-14 |
+| `pdgopkd` | Day-ahead coordinated plan (forecast demand, wind, PV, reserves) | 15 min | 2024-06-14 |
+| `poze-redoze` | Non-market redispatch of wind and PV | 15 min | 2024-09-24 |
+| `przeplywy-mocy` | Physical cross-border flows per section | 15 min, many rows | 2024-06-14 |
+| `gen-jw` | Generation per unit (≥ 100 MW) | 15 min, many rows | 2024-06-14 |
+
+Legacy export (hourly, until 2024-06-13): `PL_WYK_KSE` (demand, JWCD/nJWCD generation, exchange, from 2009),
+`PL_GEN_WIATR` (wind from 2012-05-26, PV from 2020-04-10), `PL_CENY_RYN_EN` (RCE, from 2018),
+`PL_CENY_ROZL_RB` (imbalance prices CRO of the old balancing market, from 2009). The legacy server is slow (about a
+minute per month, one month per request), so long histories take a while the first time and are then cached.
+Field descriptions, units, sources and notes for each report:
+[report catalogue](https://kwwaleszczynski-del.github.io/pse-opendata/reports/). Other endpoints of the API can
+be read raw with `pse.Client().records(endpoint, filter=...)`.
+
+## Cache and reliability
+
+- Whole months are cached as Parquet files (`$PSE_OPENDATA_CACHE` or the user cache directory; `Client(cache_dir=...)`
+  to choose, `cache_dir=None` to switch off). A month is reused only once it was downloaded after the report's
+  revision window (3 days for prices, up to 240 days for settlement volumes); the legacy history never changes.
+- Requests retry with exponential backoff on network errors, HTTP 429 and 5xx (honouring `Retry-After`) and are
+  spaced (0.2 s for the API, 15 s for the legacy export).
+- `offline=True` reads the cache only; `allow_stale=True` falls back to a cached copy when a download fails.
+- Errors are explicit: `PseApiError` (with the API's message), `UnknownReportError`, `UnknownFieldError`,
+  `CacheMissError`, `LegacyFormatError`. Logging goes to the `pse_opendata` logger.
+
+## Data source and terms of use
+
+All data come from public reports of **PSE S.A.** (Polskie Sieci Elektroenergetyczne): the reports API
+`https://api.raporty.pse.pl/api` and the export of www.pse.pl. No key is needed. This package does not include or
+redistribute PSE data, except small samples of real responses used as test fixtures (see
+[tests/fixtures/README.md](tests/fixtures/README.md)).
+
+PSE publishes conditions for re-using public sector information
+([BIP, "Ponowne wykorzystywanie informacji sektora publicznego"](https://www.pse.pl/bip/ponowne-wykorzystanie-informacji-publicznej),
+entry changed on 14 October 2026, checked on 26 October 2026). They allow commercial and non-commercial re-use of
+information published in the BIP and on www.pse.pl free of charge, on condition that you name the source and the date
+the information was obtained (e.g. "Informacja pozyskana od PSE S.A. według stanu strony www.pse.pl na dzień
+[data]"), remove the PSE logo, keep unchanged information unchanged and, when you pass on processed information, tell
+recipients that it was changed and how, without misleading them. PSE accepts no liability for processed information,
+and some materials may be protected by copyright or database rights. The conditions are written for www.pse.pl;
+the reports API is run by the same operator. When you publish results built with this package, add the attribution
+yourself, for example:
+
+> Information obtained from www.pse.pl (PSE S.A. report `rce-pln`), state as of [date]. The information has been
+> processed in whole or in part.
+
+## Documentation and development
+
+Documentation: <https://kwwaleszczynski-del.github.io/pse-opendata/> (installation, examples, catalogue, time
+pitfalls, API reference). To work on the package:
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev,docs]"     # Linux/macOS: .venv/bin/python
+pytest -q                                                 # offline, recorded responses
+pytest -q --live tests/live                               # optional: calls the real PSE servers
+ruff check .
+mypy
+mkdocs build --strict
+```
+
+## Citation
+
+If you use the package in published work, please cite it; see [`CITATION.cff`](CITATION.cff).
+
+## License
+
+Code: MIT, see [LICENSE](LICENSE). Data: PSE S.A. public reports, see
+[Data source and terms of use](#data-source-and-terms-of-use).

pse_opendata-0.2.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pse-opendata"
+dynamic = ["version"]
+description = "Unofficial Python client for the public data of PSE, the Polish transmission system operator: reports API and legacy CSV export, as tidy pandas frames with explicit interval times."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Konrad Waleszczyński" }]
+keywords = ["pse", "poland", "electricity", "power-system", "energy-market", "rce", "balancing-market", "open-data", "pandas"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pandas>=2.1",
+    "pyarrow>=14",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.10", "types-requests", "build>=1.2"]
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "mkdocstrings[python]>=0.26"]
+
+[project.urls]
+Homepage = "https://github.com/kwwaleszczynski-del/pse-opendata"
+Documentation = "https://kwwaleszczynski-del.github.io/pse-opendata/"
+Changelog = "https://github.com/kwwaleszczynski-del/pse-opendata/blob/main/CHANGELOG.md"
+
+[project.scripts]
+pse-opendata = "pse_opendata.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "pse_opendata._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pse_opendata = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = ["live: calls the real PSE servers (run with --live)"]
+# raised inside pandas 2.x with numpy >= 2.3, not by this package
+filterwarnings = ["ignore:The 'generic' unit for NumPy timedelta:DeprecationWarning"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pse_opendata"]
+known-local-folder = ["conftest"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+files = ["src"]

pse_opendata-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pse_opendata-0.2.0/src/pse_opendata/__init__.py

@@ -0,0 +1,110 @@
+"""pse-opendata: unofficial client for the public data of PSE, the Polish transmission system operator.
+
+Quick start:
+    import pse_opendata as pse
+    rce = pse.rce("2025-01-01", "2025-01-31")          # RCE price, 15-minute rows
+    sys = pse.get("his-wlk-cal", "2025-06-01", fields=["demand", "wi", "pv"])
+    demand = pse.history("demand", "2019-01-01", "2025-12-31")   # legacy export + API, hourly
+
+Module-level functions use a shared default :class:`Client` (default cache directory, see
+:mod:`pse_opendata.cache`); pass ``client=Client(...)`` to any of them to change the settings.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import pandas as pd
+
+from pse_opendata._version import __version__
+from pse_opendata.catalog import LEGACY_REPORTS, REPORTS, Field, LegacyReport, Report, get_legacy_report, get_report
+from pse_opendata.client import Client, DateLike, MonthLoad
+from pse_opendata.exceptions import (
+    CacheMissError,
+    LegacyFormatError,
+    PseApiError,
+    PseError,
+    UnknownFieldError,
+    UnknownReportError,
+)
+from pse_opendata.frames import TIME_COLUMNS, to_hourly
+from pse_opendata.stitch import splice_factor
+
+logging.getLogger("pse_opendata").addHandler(logging.NullHandler())
+
+__all__ = [
+    "LEGACY_REPORTS", "REPORTS", "TIME_COLUMNS", "CacheMissError", "Client", "Field", "LegacyFormatError",
+    "LegacyReport", "MonthLoad", "PseApiError", "PseError", "Report", "UnknownFieldError", "UnknownReportError",
+    "__version__", "balancing_capacity", "default_client", "fundamentals", "get", "get_legacy_report", "get_report",
+    "history", "imbalance_prices", "legacy", "rce", "reports", "sdac", "splice_factor", "to_hourly",
+]
+
+_default: Client | None = None
+
+
+def default_client() -> Client:
+    """The shared client used by the module-level functions (created on first use)."""
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def get(report: str, start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+        **kwargs: Any) -> pd.DataFrame:
+    """Data of a report of the reports API; see :meth:`Client.get`."""
+    return (client or default_client()).get(report, start, end, **kwargs)
+
+
+def legacy(code: str, start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+           **kwargs: Any) -> pd.DataFrame:
+    """Hourly data of the legacy CSV export; see :meth:`Client.legacy`."""
+    return (client or default_client()).legacy(code, start, end, **kwargs)
+
+
+def history(series: str, start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+            **kwargs: Any) -> pd.DataFrame:
+    """Hourly series stitched from the legacy export and the API; see :meth:`Client.history`."""
+    return (client or default_client()).history(series, start, end, **kwargs)
+
+
+def rce(start: DateLike, end: DateLike | None = None, *, client: Client | None = None, **kwargs: Any) -> pd.DataFrame:
+    """RCE price (``rce-pln``); see :meth:`Client.rce`."""
+    return (client or default_client()).rce(start, end, **kwargs)
+
+
+def sdac(start: DateLike, end: DateLike | None = None, *, client: Client | None = None, **kwargs: Any) -> pd.DataFrame:
+    """SDAC price for Poland (``csdac-pln``); see :meth:`Client.sdac`."""
+    return (client or default_client()).sdac(start, end, **kwargs)
+
+
+def fundamentals(start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+                 **kwargs: Any) -> pd.DataFrame:
+    """Demand, generation and exchange (``his-wlk-cal``); see :meth:`Client.fundamentals`."""
+    return (client or default_client()).fundamentals(start, end, **kwargs)
+
+
+def imbalance_prices(start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+                     **kwargs: Any) -> pd.DataFrame:
+    """Imbalance and balancing energy prices (``crb-rozl``); see :meth:`Client.imbalance_prices`."""
+    return (client or default_client()).imbalance_prices(start, end, **kwargs)
+
+
+def balancing_capacity(start: DateLike, end: DateLike | None = None, *, client: Client | None = None,
+                       **kwargs: Any) -> pd.DataFrame:
+    """Balancing capacity prices and volumes; see :meth:`Client.balancing_capacity`."""
+    return (client or default_client()).balancing_capacity(start, end, **kwargs)
+
+
+def reports(legacy: bool = False) -> pd.DataFrame:
+    """The catalogue as a frame: one row per report of the reports API (or of the legacy export)."""
+    if legacy:
+        rows = [{"code": r.code, "title": r.title, "title_pl": r.title_pl, "resolution": r.resolution,
+                 "first_date": r.first_date, "last_date": r.last_date, "fields": ", ".join(r.field_names),
+                 "page": r.page} for r in LEGACY_REPORTS.values()]
+    else:
+        rows = [{"name": r.name, "title": r.title, "title_pl": r.title_pl, "group": r.group,
+                 "resolution": r.resolution, "first_date": r.first_date, "revision_days": r.revision_days,
+                 "fields": ", ".join(r.field_names), "verified": r.verified, "url": r.url} for r in REPORTS.values()]
+    return pd.DataFrame(rows)

pse_opendata-0.2.0/src/pse_opendata/__main__.py

@@ -0,0 +1,3 @@
+from pse_opendata.cli import main
+
+raise SystemExit(main())