python-esios 2.2.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

esios/managers/indicators.py

@@ -142,6 +142,7 @@ class IndicatorHandle:
         geo_agg: str | None = None,
         time_trunc: str | None = None,
         geo_trunc: str | None = None,
+        column_name: str | None = None,
     ) -> pd.DataFrame:
         """Fetch historical values as a DataFrame with DatetimeIndex.
 
@@ -151,6 +152,12 @@ class IndicatorHandle:
         When multiple geo_ids are present (e.g. indicator 600 returns data for
         several countries), the result is pivoted so each geo becomes a column
         named by its geo_name. Use *geo_ids* to filter to specific geos.
+
+        Args:
+            column_name: If provided, rename the output column(s) to this name.
+                Useful for single-column results where a stable name like
+                ``"value"`` is preferred over the default geo_name or
+                indicator ID.
         """
         base_params: dict[str, Any] = {
             "locale": locale,
@@ -250,7 +257,7 @@ class IndicatorHandle:
             if existing:
                 result = result[existing]
 
-        return self._finalize(result)
+        return self._finalize(result, column_name=column_name)
 
     def _to_wide(self, values: list[dict]) -> pd.DataFrame:
         """Convert raw API value dicts to wide-format DataFrame.
@@ -283,16 +290,26 @@ class IndicatorHandle:
         df = df.drop(columns=geo_drop, errors="ignore")
         return df
 
-    def _finalize(self, df: pd.DataFrame) -> pd.DataFrame:
+    def _finalize(
+        self, df: pd.DataFrame, *, column_name: str | None = None,
+    ) -> pd.DataFrame:
         """Prepare DataFrame for user-facing output.
 
         Cache stores columns as str(geo_id). This method renames them to
         human-readable geo_names at the very end, just before returning to
         the caller. Single-value/single-geo indicators get the indicator ID.
+
+        If ``column_name`` is provided and the result has a single column,
+        that column is renamed to ``column_name`` (e.g. ``"value"``).
         """
         if df.empty:
             return df
 
+        # If caller wants a specific column name and there's a single column, use it
+        if column_name and len(df.columns) == 1:
+            df = df.rename(columns={df.columns[0]: column_name})
+            return df
+
         if len(df.columns) == 1:
             col = df.columns[0]
             if col == "value":
@@ -305,11 +322,15 @@ class IndicatorHandle:
         if rename:
             df = df.rename(columns=rename)
 
+        # If caller wants a specific column name for multi-column, skip
+        # (ambiguous which column to rename)
+        if column_name and len(df.columns) == 1:
+            df = df.rename(columns={df.columns[0]: column_name})
+            return df
+
         # Single-geo after rename: use indicator ID as column name
         if len(df.columns) == 1:
             col = df.columns[0]
-            # If the single column is a geo_name, keep it (user filtered to one geo)
-            # If it's still a geo_id string, rename to indicator ID
             if col not in geo_map.values():
                 df = df.rename(columns={col: str(self.id)})
 

esios/processing/i90.py

@@ -166,11 +166,15 @@ class I90Sheet:
     def _normalize_datetime_columns(self, columns: np.ndarray) -> np.ndarray:
         """Normalize time column headers to integer period indices.
 
-        Handles three column formats found in I90 files:
-        - Sequential integers 1–24 (hourly) or 1–96 (quarterly)
-        - H-Q format with dash notation: "1-1", "1-2", "1-3", "1-4", "2-1", …
-        - NaN-filler format: [1, NaN, NaN, NaN, 2, …] (one label per hour,
-          three trailing NaNs for quarters 2–4)
+        Handles four column formats found in I90 files:
+
+        1. Sequential integers: 1–24 (hourly) or 1–96 (quarterly)
+        2. H-Q format: "1-1", "1-2", "1-3", "1-4", "2-1", …
+        3. NaN-filler format: [1, NaN, NaN, NaN, 2, …]
+        4. Range format (DST days): "00-01", "01-02", "02-03a", "02-03b", …
+           where the first number is the start hour and a/b suffix marks
+           the repeated hour on fall-back days. Detected by the first
+           column starting with "0" (e.g. "00-01").
         """
         if any(pd.isna(columns)):
             self._n_columns_totals = 3
@@ -178,6 +182,17 @@ class I90Sheet:
             self._n_columns_totals = 2
 
         series = pd.Series(columns, dtype=str).ffill()
+
+        # Range format (DST): "00-01", "01-02", "02-03a", "02-03b", ...
+        # Detected by first column starting with "0" (sequential ints start at 1).
+        first_val = str(columns[0]).strip()
+        if first_val.startswith("0") and "-" in first_val:
+            # Simply assign sequential 1-based indices.
+            # The count of columns (23, 24, or 25 for hourly; 92, 96, or 100
+            # for QH) already encodes the DST information. The datetime builder
+            # in _preprocess uses these as offsets from midnight UTC.
+            return np.arange(1, len(columns) + 1)
+
         parts = series.str.split("-")
         hours = parts.str[0].astype(float).astype(int)
 
@@ -251,12 +266,18 @@ class I90Sheet:
                 self.frequency = "hourly"
                 time_deltas = columns_date * 60  # minutes
 
-            # Build datetime index
-            base_date = pd.to_datetime(self.metadata["date_data"])
-            columns_datetime = base_date + pd.to_timedelta(time_deltas, unit="m")
-            columns_datetime = pd.DatetimeIndex(columns_datetime).tz_localize(
-                "Europe/Madrid", ambiguous="infer"
-            )
+            # Build datetime index in UTC to avoid DST ambiguity.
+            # On fall-back days (Oct), I90 has 25 hourly periods (or 100 QH).
+            # Naïve offset arithmetic creates a single 02:00 that tz_localize
+            # cannot disambiguate.  By anchoring midnight in Europe/Madrid,
+            # converting to UTC, then adding offsets, each period maps to a
+            # unique UTC instant — no ambiguity.
+            # On spring-forward days (Mar), I90 has 23 periods (or 92 QH)
+            # and this approach naturally skips the non-existent hour.
+            midnight_utc = pd.Timestamp(
+                self.metadata["date_data"], tz="Europe/Madrid"
+            ).tz_convert("UTC")
+            columns_datetime = midnight_utc + pd.to_timedelta(time_deltas, unit="m")
 
             data = pd.DataFrame(self.rows[idx + 1 :], columns=columns)
 

{python_esios-2.2.0.dist-info → python_esios-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-esios
-Version: 2.2.0
+Version: 2.3.0
 Summary: A Python wrapper for the ESIOS API (Spanish electricity market)
 Project-URL: Homepage, https://github.com/datons/python-esios
 Project-URL: Repository, https://github.com/datons/python-esios

{python_esios-2.2.0.dist-info → python_esios-2.3.0.dist-info}/RECORD

@@ -24,7 +24,7 @@ esios/data/time_periods.yaml,sha256=oyisKYYyOGA57eEAqkFFx6B3x9rdSl0DokZe5gNZfMw,
 esios/managers/__init__.py,sha256=-1AwL7arUf7WEZn1RSiK_DZhY3j6U4GE9_dqjbukCJc,268
 esios/managers/archives.py,sha256=PG-1gQYEiJUVQQtTKIZeEoWIsS-gkWT3ZHy89c8tTW8,9293
 esios/managers/base.py,sha256=7XcdrUtUOPuqfHYlz4w562TD8o9cNdBWOgs4CHHonoo,835
-esios/managers/indicators.py,sha256=GEyHq09TCPnf3ARULS7olJYC6iiom2XrcyhDAf946po,16653
+esios/managers/indicators.py,sha256=nbmKsvBTPO2w3FlcVYv9WOtCTU8xMjFvT_d1AcA2sbg,17506
 esios/managers/offer_indicators.py,sha256=0MjEKkj77YC2fRSHVTEc7FW6E8AuwwciAXK-bOVEL5Q,4187
 esios/models/__init__.py,sha256=oppuTASpf0Dh2KbGMXInULT0F4sELjeo-9UhPiPOZiA,289
 esios/models/archive.py,sha256=P2LaT7_ff4ujwqVn_ofgQP3dbpf7jqON0R22dKwSJ_w,1062
@@ -32,10 +32,10 @@ esios/models/indicator.py,sha256=u1AJyEA3YeOqQFjV08_lzyMaofuCiMoLPjvosls9gfE,111
 esios/models/offer_indicator.py,sha256=nA80Y7Yp0utDaDOdZ-ObcWTsAdhvuXlfJjJBpdVQ7Lo,758
 esios/processing/__init__.py,sha256=1kLt_gO_wDhXM1BbY0zTyfAYo-CjYKW1ljgRRDZ7USM,278
 esios/processing/dataframes.py,sha256=OitzBvAerssGP2VXNC-sSO48XsHdIB2nKTUgByN5eYQ,2524
-esios/processing/i90.py,sha256=k4RH4lIwIm04ASYnubdQwJ3WM98iLj5l14zwxXBQEBo,10443
+esios/processing/i90.py,sha256=fI8DfY8CD2kF1_ZrAzuEDxN0m7Vh3CV3dIn32lxKffA,11687
 esios/processing/zip.py,sha256=12LbFHJTdX_h3JG-clEgQ4Haj-kw0UjfopGLlCRXfGM,1913
-python_esios-2.2.0.dist-info/METADATA,sha256=ZnkUUArmCnyVe_kDuOhjm-JzXWXeqKN9irD39vT0YpI,3169
-python_esios-2.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_esios-2.2.0.dist-info/entry_points.txt,sha256=7ngseyIyvJ4buTHFL9htaZ4tTFHpG4zzJNkc8B5Jr8U,40
-python_esios-2.2.0.dist-info/licenses/LICENSE,sha256=LorLs1-VeBW70Wo9fLAtLJN7nNd6Poy0xzvqdWVqFlE,35128
-python_esios-2.2.0.dist-info/RECORD,,
+python_esios-2.3.0.dist-info/METADATA,sha256=KtWOIGA-o9z7mxZD8vryWTOntVZbxNm_LIVaXYhFD3g,3169
+python_esios-2.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_esios-2.3.0.dist-info/entry_points.txt,sha256=7ngseyIyvJ4buTHFL9htaZ4tTFHpG4zzJNkc8B5Jr8U,40
+python_esios-2.3.0.dist-info/licenses/LICENSE,sha256=LorLs1-VeBW70Wo9fLAtLJN7nNd6Poy0xzvqdWVqFlE,35128
+python_esios-2.3.0.dist-info/RECORD,,