python-entsoe 0.6.2__tar.gz → 0.7.0__tar.gz

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.0](https://gitlab.com/datons.com/libraries/python-entsoe/-/tags/v0.7.0) (2026-11-02)
+
+### Features
+
+* **timezones:** configure result timestamps as UTC (default), local area time, or a fixed IANA timezone through the client, per-call override, or CLI `--tz` and persistent `output-tz` setting.
+
+## [0.6.3](https://gitlab.com/datons.com/libraries/python-entsoe/-/tags/v0.6.3) (2026-10-15)
+
+
+### Bug Fixes
+
+* **cli:** `--period today` and `--period yesterday` produced an empty range and always failed with "start must be before end"; each now covers the full day.
+* **cache:** a failed download (timeout, HTTP error) no longer returns an empty or partial DataFrame with only a warning in the log; the error is raised.
+
 ## [0.6.2](https://gitlab.com/datons.com/libraries/python-entsoe/-/tags/v0.6.2) (2026-10-15)
 
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-entsoe
-Version: 0.6.2
+Version: 0.7.0
 Summary: Python client for the ENTSO-E Transparency Platform API
 Project-URL: Homepage, https://gitlab.com/datons.com/libraries/python-entsoe
 Project-URL: Repository, https://gitlab.com/datons.com/libraries/python-entsoe
@@ -57,7 +57,7 @@ start = pd.Timestamp("2024-06-01", tz="Europe/Paris")
 df = client.load.actual(start, "2024-06-08", country="FR")
 ```
 
-Every method returns a `pandas.DataFrame` with a `timestamp` column (UTC) and a `value` column.
+Every method returns a `pandas.DataFrame` with a timezone-aware `timestamp` column and a `value` column.
 
 ## Authentication
 
@@ -216,7 +216,11 @@ df = client.load.actual("2024-01-01", pd.Timestamp("2024-01-07", tz="UTC"), coun
 start = pd.Timestamp("2024-01-01")  # ← no tz, will error
 ```
 
-Returned timestamps are always in **UTC**.
+## Timezones
+
+The client `tz` setting interprets input date strings (default `Europe/Brussels`); it does not control returned timestamps. The separate `output_tz` setting controls results: `"UTC"` (default, unchanged behavior), `"local"` (the requested area's timezone), or a fixed IANA timezone such as `"Europe/Madrid"`. Every namespace method also accepts `output_tz=` for one call. The CLI accepts `--tz` on data commands, or `entsoe config set output-tz local` as a persistent default; `--tz` takes precedence.
+
+For a multi-area request, `"local"` requires matching clock offsets throughout the returned period (for example, FR and ES); otherwise choose `"UTC"` or a fixed IANA zone. Cross-border results use the first importing (`in_domain`) zone. During the October DST fall-back, local wall-clock times repeat; each row retains its offset, but timestamps cease to be unique if the timezone is stripped.
 
 ## Features
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/README.md

@@ -29,7 +29,7 @@ start = pd.Timestamp("2024-06-01", tz="Europe/Paris")
 df = client.load.actual(start, "2024-06-08", country="FR")
 ```
 
-Every method returns a `pandas.DataFrame` with a `timestamp` column (UTC) and a `value` column.
+Every method returns a `pandas.DataFrame` with a timezone-aware `timestamp` column and a `value` column.
 
 ## Authentication
 
@@ -188,7 +188,11 @@ df = client.load.actual("2024-01-01", pd.Timestamp("2024-01-07", tz="UTC"), coun
 start = pd.Timestamp("2024-01-01")  # ← no tz, will error
 ```
 
-Returned timestamps are always in **UTC**.
+## Timezones
+
+The client `tz` setting interprets input date strings (default `Europe/Brussels`); it does not control returned timestamps. The separate `output_tz` setting controls results: `"UTC"` (default, unchanged behavior), `"local"` (the requested area's timezone), or a fixed IANA timezone such as `"Europe/Madrid"`. Every namespace method also accepts `output_tz=` for one call. The CLI accepts `--tz` on data commands, or `entsoe config set output-tz local` as a persistent default; `--tz` takes precedence.
+
+For a multi-area request, `"local"` requires matching clock offsets throughout the returned period (for example, FR and ES); otherwise choose `"UTC"` or a fixed IANA zone. Cross-border results use the first importing (`in_domain`) zone. During the October DST fall-back, local wall-clock times repeat; each row retains its offset, but timestamps cease to be unique if the timezone is stripped.
 
 ## Features
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-entsoe"
-version = "0.6.2"
+version = "0.7.0"
 description = "Python client for the ENTSO-E Transparency Platform API"
 readme = "README.md"
 license = "MIT"

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/_mappings.py

@@ -64,6 +64,30 @@ AREA_CODES: dict[str, str] = {
     "XK": "10Y1001C--00100H",
 }
 
+# IANA timezone of each ENTSO-E bidding area. Keys intentionally mirror AREA_CODES.
+AREA_TZ: dict[str, str] = {
+    "AL": "Europe/Tirane", "AT": "Europe/Vienna", "BA": "Europe/Sarajevo",
+    "BE": "Europe/Brussels", "BG": "Europe/Sofia", "CH": "Europe/Zurich",
+    "CZ": "Europe/Prague", "DE": "Europe/Berlin", "DE_LU": "Europe/Berlin",
+    "DE_AT_LU": "Europe/Berlin", "DK": "Europe/Copenhagen",
+    "DK_1": "Europe/Copenhagen", "DK_2": "Europe/Copenhagen",
+    "EE": "Europe/Tallinn", "ES": "Europe/Madrid", "FI": "Europe/Helsinki",
+    "FR": "Europe/Paris", "GB": "Europe/London", "GR": "Europe/Athens",
+    "HR": "Europe/Zagreb", "HU": "Europe/Budapest", "IE": "Europe/Dublin",
+    "IE_SEM": "Europe/Dublin", "IT": "Europe/Rome", "IT_NORTH": "Europe/Rome",
+    "IT_CNOR": "Europe/Rome", "IT_CSUD": "Europe/Rome", "IT_SUD": "Europe/Rome",
+    "IT_SICI": "Europe/Rome", "IT_SARD": "Europe/Rome", "LT": "Europe/Vilnius",
+    "LU": "Europe/Luxembourg", "LV": "Europe/Riga", "ME": "Europe/Podgorica",
+    "MK": "Europe/Skopje", "MT": "Europe/Malta", "NL": "Europe/Amsterdam",
+    "NO": "Europe/Oslo", "NO_1": "Europe/Oslo", "NO_2": "Europe/Oslo",
+    "NO_3": "Europe/Oslo", "NO_4": "Europe/Oslo", "NO_5": "Europe/Oslo",
+    "PL": "Europe/Warsaw", "PT": "Europe/Lisbon", "RO": "Europe/Bucharest",
+    "RS": "Europe/Belgrade", "SE": "Europe/Stockholm", "SE_1": "Europe/Stockholm",
+    "SE_2": "Europe/Stockholm", "SE_3": "Europe/Stockholm", "SE_4": "Europe/Stockholm",
+    "SI": "Europe/Ljubljana", "SK": "Europe/Bratislava", "TR": "Europe/Istanbul",
+    "UA": "Europe/Kyiv", "UK": "Europe/London", "XK": "Europe/Belgrade",
+}
+
 # ISO code → human-readable country/area name
 COUNTRY_NAMES: dict[str, str] = {
     "AL": "Albania",

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/_output.py

@@ -34,7 +34,10 @@ def output(df, format: str, title: str = "", output_path: str | None = None):
             typer.echo(text)
 
     elif format == "json":
-        text = df.to_json(orient="records", indent=2, date_format="iso")
+        display = df.copy()
+        if "timestamp" in display:
+            display["timestamp"] = display["timestamp"].map(lambda value: value.isoformat())
+        text = display.to_json(orient="records", indent=2)
         if output_path:
             with open(output_path, "w") as f:
                 f.write(text)
@@ -72,7 +75,10 @@ def render_result(result, format: str, output_path: str | None) -> None:
         if format == "csv":
             text = result.to_csv()
         elif format == "json":
-            text = result.to_json(orient="records", indent=2, date_format="iso")
+            display = result.copy()
+            if "timestamp" in display:
+                display["timestamp"] = display["timestamp"].map(lambda value: value.isoformat())
+            text = display.to_json(orient="records", indent=2)
         else:
             table = Table()
             idx_name = result.index.name or ""

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/_resolve.py

@@ -100,11 +100,11 @@ def _expand_period(period: str, today: date) -> tuple[date, date]:
 
     p = period.lower().strip()
 
+    # The library's end is exclusive, so a single day ends on the next one.
     if p == "today":
-        return today, today
+        return today, today + timedelta(days=1)
     if p == "yesterday":
-        yesterday = today - timedelta(days=1)
-        return yesterday, yesterday
+        return today - timedelta(days=1), today
     if p == "week":
         monday = today - timedelta(days=today.weekday())
         return monday, today

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/app.py

@@ -6,7 +6,7 @@ from typing import Optional
 
 import typer
 
-from entsoe.cli.config import get_api_key
+from entsoe.cli.config import get_api_key, get_config
 
 app = typer.Typer(
     name="entsoe",
@@ -15,7 +15,7 @@ app = typer.Typer(
 )
 
 
-def get_client(api_key: str | None = None):
+def get_client(api_key: str | None = None, output_tz: str | None = None):
     """Lazy import + construct client."""
     from entsoe.client import ENTSOEClient
 
@@ -26,7 +26,8 @@ def get_client(api_key: str | None = None):
             err=True,
         )
         raise typer.Exit(1)
-    return ENTSOEClient(api_key=resolved)
+    configured_tz = get_config("output-tz") if output_tz is None else output_tz
+    return ENTSOEClient(api_key=resolved, output_tz="UTC" if configured_tz is None else configured_tz)
 
 
 # -- Register sub-commands ---------------------------------------------------

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/balancing.py

@@ -21,12 +21,13 @@ def prices(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query imbalance prices."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     countries = resolve_many_required(country)
     df = client.balancing.imbalance_prices(s, e, country=countries)
     output(df, format, title="Imbalance Prices", output_path=output_path)
@@ -41,12 +42,13 @@ def volumes(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query imbalance volumes."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     countries = resolve_many_required(country)
     df = client.balancing.imbalance_volumes(s, e, country=countries)
     output(df, format, title="Imbalance Volumes", output_path=output_path)

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/config_cmd.py

@@ -9,12 +9,16 @@ config_app = typer.Typer(no_args_is_help=True)
 
 @config_app.command("set")
 def config_set(
-    key: str = typer.Argument(..., help="Configuration key (e.g., 'api-key')"),
+    key: str = typer.Argument(..., help="Configuration key (api-key or output-tz)"),
     value: str = typer.Argument(..., help="Configuration value"),
 ):
     """Set a configuration value."""
     from entsoe.cli.config import set_config
 
+    if key == "output-tz":
+        from entsoe.namespaces._base import validate_output_tz
+        validate_output_tz(value)
+
     set_config(key, value)
     typer.echo(f"Set {key} = {'***' if 'key' in key.lower() else value}")
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/exec_cmd.py

@@ -62,6 +62,7 @@ def exec_prices(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Fetch price data and evaluate a Python expression.
 
@@ -73,7 +74,7 @@ def exec_prices(
 
     method_name = _resolve_method(method, _PRICES_METHODS)
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     fn = getattr(client.prices, method_name)
     df = fn(s, e, country=resolve_many_required(country))
     _eval_and_render(df, expr, format, output_path)
@@ -96,6 +97,7 @@ def exec_load(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Fetch load data and evaluate a Python expression.
 
@@ -107,7 +109,7 @@ def exec_load(
 
     method_name = _resolve_method(method, _LOAD_METHODS)
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     fn = getattr(client.load, method_name)
     df = fn(s, e, country=resolve_many_required(country))
     _eval_and_render(df, expr, format, output_path)
@@ -136,6 +138,7 @@ def exec_generation(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Fetch generation data and evaluate a Python expression.
 
@@ -147,7 +150,7 @@ def exec_generation(
 
     method_name = _resolve_method(method, _GENERATION_METHODS)
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     fn = getattr(client.generation, method_name)
     df = fn(s, e, country=resolve_many_required(country), psr_type=resolve_many(psr))
     _eval_and_render(df, expr, format, output_path)
@@ -176,6 +179,7 @@ def exec_transmission(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Fetch transmission data and evaluate a Python expression.
 
@@ -200,7 +204,7 @@ def exec_transmission(
         typer.echo("Error: Provide --from/--to or --border.", err=True)
         raise typer.Exit(1)
 
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     fn = getattr(client.transmission, method_name)
     df = fn(s, e, **kwargs)
     _eval_and_render(df, expr, format, output_path)
@@ -223,6 +227,7 @@ def exec_balancing(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Fetch balancing data and evaluate a Python expression.
 
@@ -234,7 +239,7 @@ def exec_balancing(
 
     method_name = _resolve_method(method, _BALANCING_METHODS)
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     fn = getattr(client.balancing, method_name)
     df = fn(s, e, country=resolve_many_required(country))
     _eval_and_render(df, expr, format, output_path)

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/generation.py

@@ -22,12 +22,13 @@ def actual(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query actual generation output per type."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.generation.actual(s, e, country=resolve_many_required(country), psr_type=resolve_many(psr))
     output(df, format, title="Actual Generation", output_path=output_path)
 
@@ -42,12 +43,13 @@ def forecast(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query day-ahead generation forecast (wind/solar)."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.generation.forecast(s, e, country=resolve_many_required(country), psr_type=resolve_many(psr))
     output(df, format, title="Generation Forecast", output_path=output_path)
 
@@ -62,12 +64,13 @@ def capacity(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query installed generation capacity per type."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.generation.installed_capacity(s, e, country=resolve_many_required(country), psr_type=resolve_many(psr))
     output(df, format, title="Installed Capacity", output_path=output_path)
 
@@ -82,12 +85,13 @@ def per_plant(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query actual generation per production unit."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.generation.per_plant(s, e, country=resolve_many_required(country), psr_type=resolve_many(psr))
     output(df, format, title="Generation Per Plant", output_path=output_path)
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/load.py

@@ -21,12 +21,13 @@ def actual(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query actual total system load."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     countries = resolve_many_required(country)
     df = client.load.actual(s, e, country=countries)
     output(df, format, title="Actual Load", output_path=output_path)
@@ -41,12 +42,13 @@ def forecast(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query day-ahead load forecast."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     countries = resolve_many_required(country)
     df = client.load.forecast(s, e, country=countries)
     output(df, format, title="Load Forecast", output_path=output_path)

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/prices.py

@@ -22,12 +22,13 @@ def day_ahead(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query day-ahead electricity prices."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     countries = resolve_many_required(country)
     df = client.prices.day_ahead(s, e, country=countries, sequence=sequence)
     output(df, format, title="Day-Ahead Prices", output_path=output_path)

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/cli/transmission.py

@@ -43,13 +43,14 @@ def flows(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query physical cross-border flows."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
     kwargs = _resolve_borders_or_pairs(country_from, country_to, border)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.transmission.crossborder_flows(s, e, **kwargs)
     output(df, format, title="Cross-Border Flows", output_path=output_path)
 
@@ -65,13 +66,14 @@ def exchanges(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query scheduled commercial exchanges (day-ahead)."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
     kwargs = _resolve_borders_or_pairs(country_from, country_to, border)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.transmission.scheduled_exchanges(s, e, **kwargs)
     output(df, format, title="Scheduled Exchanges", output_path=output_path)
 
@@ -87,13 +89,14 @@ def capacity(
     format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
     output_path: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
     api_key: Optional[str] = typer.Option(None, "--api-key", help="ENTSO-E API key"),
+    tz: Optional[str] = typer.Option(None, "--tz", help="Output timezone: UTC, local, or IANA name"),
 ):
     """Query day-ahead net transfer capacity."""
     from entsoe.cli.app import get_client
 
     s, e = resolve_dates(start, end, period)
     kwargs = _resolve_borders_or_pairs(country_from, country_to, border)
-    client = get_client(api_key)
+    client = get_client(api_key, tz)
     df = client.transmission.net_transfer_capacity(s, e, **kwargs)
     output(df, format, title="Net Transfer Capacity", output_path=output_path)
 

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/client.py

@@ -7,6 +7,7 @@ from pathlib import Path
 
 from ._http import HttpClient
 from .cache import CacheConfig, CacheStore
+from .namespaces._base import validate_output_tz
 from .namespaces import (
     BalancingNamespace,
     GenerationNamespace,
@@ -38,6 +39,8 @@ class ENTSOEClient:
 
         # Override default timezone
         client = ENTSOEClient(tz="UTC")
+        client = ENTSOEClient(output_tz="local")  # results use each zone's local time
+        client = ENTSOEClient(output_tz="Europe/Madrid")  # fixed output zone
 
         # Disable cache
         client = ENTSOEClient(cache=False)
@@ -60,6 +63,7 @@ class ENTSOEClient:
         cache: bool = True,
         cache_dir: str | Path | None = None,
         cache_recent_ttl: int = 48,
+        output_tz: str = "UTC",
     ) -> None:
         """Initialize the client.
 
@@ -71,10 +75,13 @@ class ENTSOEClient:
             cache: Whether to enable local parquet caching. Defaults to True.
             cache_dir: Custom cache directory. Defaults to ``~/.cache/entsoe/``.
             cache_recent_ttl: Hours before data is considered final (default 48).
+            output_tz: Result timezone: ``UTC`` (default), ``local`` for the requested area, or an IANA name.
 
         Raises:
             ValueError: If no API key is found.
+            InvalidParameterError: If output_tz is not UTC, local, or a valid IANA timezone.
         """
+        output_tz = validate_output_tz(output_tz)
         resolved_key = api_key or os.environ.get("ENTSOE_API_KEY")
         if not resolved_key:
             raise ValueError(
@@ -94,11 +101,11 @@ class ENTSOEClient:
 
         cache_store = CacheStore(cache_config) if cache else None
 
-        self.load = LoadNamespace(http, tz=tz, cache=cache_store)
-        self.prices = PricesNamespace(http, tz=tz, cache=cache_store)
-        self.generation = GenerationNamespace(http, tz=tz, cache=cache_store)
-        self.transmission = TransmissionNamespace(http, tz=tz, cache=cache_store)
-        self.balancing = BalancingNamespace(http, tz=tz, cache=cache_store)
+        self.load = LoadNamespace(http, tz=tz, output_tz=output_tz, cache=cache_store)
+        self.prices = PricesNamespace(http, tz=tz, output_tz=output_tz, cache=cache_store)
+        self.generation = GenerationNamespace(http, tz=tz, output_tz=output_tz, cache=cache_store)
+        self.transmission = TransmissionNamespace(http, tz=tz, output_tz=output_tz, cache=cache_store)
+        self.balancing = BalancingNamespace(http, tz=tz, output_tz=output_tz, cache=cache_store)
 
         # Expose for CLI cache commands
         self._cache = cache_store

{python_entsoe-0.6.2 → python_entsoe-0.7.0}/src/entsoe/namespaces/_base.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 import logging
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 from typing import TYPE_CHECKING, Callable, Optional, Union
 
 import pandas as pd
 
-from ..exceptions import InvalidParameterError, NoDataError
-from .._mappings import country_name, lookup_area
+from ..exceptions import InvalidParameterError
+from .._mappings import AREA_TZ, EIC_TO_ISO, country_name, lookup_area
 
 if TYPE_CHECKING:
     import xml.etree.ElementTree as ET
@@ -28,6 +29,52 @@ OneOrMany = Union[str, list[str]]
 TimeSeriesFilter = Optional[Callable[["ET.Element"], bool]]
 
 
+def validate_output_tz(value: str) -> str:
+    """Validate an output timezone without changing its spelling."""
+    if value == "local":
+        return value
+    if not isinstance(value, str):
+        raise InvalidParameterError("output_tz must be 'UTC', 'local', or an IANA timezone.")
+    try:
+        ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError):
+        raise InvalidParameterError(
+            f"Invalid output_tz {value!r}; use 'UTC', 'local', or an IANA timezone."
+        ) from None
+    return value
+
+
+def _to_output_tz(df: pd.DataFrame, zones: OneOrMany, output_tz: str) -> pd.DataFrame:
+    """Convert a UTC result at the namespace boundary without mutating cached data.
+
+    For cross-border requests, callers pass the first in_domain zone; local time then follows that zone.
+    """
+    target = validate_output_tz(output_tz)
+    if target == "UTC":
+        return df
+    if target == "local":
+        requested = [zones] if isinstance(zones, str) else zones
+        timezones = [AREA_TZ[EIC_TO_ISO[lookup_area(zone)]] for zone in requested]
+        instants = df["timestamp"].drop_duplicates() if "timestamp" in df else []
+        if not len(instants):
+            instants = [pd.Timestamp("2024-01-01", tz="UTC"), pd.Timestamp("2024-07-01", tz="UTC")]
+        signatures = {
+            zone: tuple(instant.to_pydatetime().astimezone(ZoneInfo(zone)).utcoffset() for instant in instants)
+            for zone in set(timezones)
+        }
+        if len(set(signatures.values())) != 1:
+            raise InvalidParameterError(
+                f"Local output spans different timezones: {', '.join(sorted(set(timezones)))}. "
+                "Use 'UTC' or a fixed IANA timezone."
+            )
+        target = timezones[0]
+    if df.empty or "timestamp" not in df:
+        return df.copy()
+    result = df.copy()
+    result["timestamp"] = result["timestamp"].dt.tz_convert(target)
+    return result
+
+
 class BaseNamespace:
     """Base class for domain namespaces.
 
@@ -40,12 +87,17 @@ class BaseNamespace:
         http: HttpClient,
         *,
         tz: str = "Europe/Brussels",
+        output_tz: str = "UTC",
         cache: CacheStore | None = None,
     ) -> None:
         self._http = http
         self._tz = tz
+        self._output_tz = validate_output_tz(output_tz)
         self._cache = cache
 
+    def _output(self, df: pd.DataFrame, zones: OneOrMany, output_tz: str | None) -> pd.DataFrame:
+        return _to_output_tz(df, zones, self._output_tz if output_tz is None else output_tz)
+
     # ------------------------------------------------------------------
     # Timestamp coercion
     # ------------------------------------------------------------------
@@ -232,17 +284,14 @@ class BaseNamespace:
         )
         new_wide_frames = []
         gap_meta: dict = {}
+        # A failed request propagates: returning the cache without the gap
+        # would silently hand back partial or empty data.
         for gap in valid_gaps:
-            try:
-                raw_df = self._query(params, gap.start, gap.end, ts_filter=ts_filter)
-                wide, meta = self._to_wide(raw_df, pivot_col, value_col)
-                new_wide_frames.append(wide)
-                if meta:
-                    gap_meta.update(meta)
-            except (InvalidParameterError, NoDataError):
-                raise
-            except Exception as exc:
-                logger.warning("Failed to fetch gap %s→%s: %s", gap.start, gap.end, exc)
+            raw_df = self._query(params, gap.start, gap.end, ts_filter=ts_filter)
+            wide, meta = self._to_wide(raw_df, pivot_col, value_col)
+            new_wide_frames.append(wide)
+            if meta:
+                gap_meta.update(meta)
 
         # 4. Merge new data with cache and persist
         if new_wide_frames: