rename roll_utc_offset in get_pvgis_tmy

- refactor utc_offset everywhere including comments and docstring
- add additional test to coerce year even if utc offset is zero or none
- change tzname to 'UTC' (versus Etc/GMT or Etc/GMT+0) if replacing with zero utc offset

Author: mikofski

pvlib/iotools/pvgis.py

@@ -395,7 +395,9 @@ def _coerce_and_roll_pvgis_tmy(pvgis_data, tz, year):
     After converting TZ, roll dataframe so timeseries starts at midnight
     and force all indices to a common year. Only works for integer TZ.
     """
-    tzname = pytz.timezone(f'Etc/GMT{-tz:+d}')
+    tzname = (
+        pytz.timezone(f'Etc/GMT{-tz:+d}') if tz != 0
+        else pytz.timezone('UTC'))
     new_index = [
         timestamp.replace(year=year, tzinfo=tzname)
         for timestamp in pvgis_data.index]
@@ -409,7 +411,7 @@ def _coerce_and_roll_pvgis_tmy(pvgis_data, tz, year):
 def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None,
                   map_variables=True, url=URL, timeout=30,
-                  utc_offset=None, coerce_year=None):
+                  roll_utc_offset=None, coerce_year=None):
     """
     Get TMY data from PVGIS.
 
@@ -441,13 +443,13 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         base url of PVGIS API, append ``tmy`` to get TMY endpoint
     timeout : int, default 30
         time in seconds to wait for server response before timeout
-    utc_offset: int, default None
+    roll_utc_offset: int, default None
         Use to specify a time zone other than the default UTC zero and roll
-        dataframe by ``utc_offset`` so it starts at midnight on January 1st.
-        Ignored if ``None``, otherwise will also force year to ``coerce_year``.
+        dataframe by ``roll_utc_offset`` so it starts at midnight on January
+        1st. Ignored if ``None``, otherwise will force year to ``coerce_year``.
     coerce_year: int, default None
         Use to force indices to desired year. Will default to 1990 if
-        ``coerce_year`` is ``None``, but ``utc_offset`` is not ``None``.
+        ``coerce_year`` is ``None``, but ``roll_utc_offset`` is not ``None``.
 
     Returns
     -------
@@ -534,15 +536,15 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
-    if utc_offset is not None or coerce_year is not None:
+    if roll_utc_offset is not None or coerce_year is not None:
         # XXX: be explicit, test for identity not implicit booleaness
-        # utc_offset None but coerce_year isn't, set year with utc zero
-        if utc_offset is None:  # XXX: None and zero are both False
-            utc_offset = 0
+        # roll_utc_offset None but coerce_year isn't, set year with utc zero
+        if roll_utc_offset is None:  # XXX: None and zero are both False
+            roll_utc_offset = 0
         # coerce_year is None but utc_off isn't, set year to 1990
         if coerce_year is None:  # more explicit than (coerce_year or 1990)
             coerce_year = 1990
-        data = _coerce_and_roll_pvgis_tmy(data, utc_offset, coerce_year)
+        data = _coerce_and_roll_pvgis_tmy(data, roll_utc_offset, coerce_year)
 
     return data, months_selected, inputs, meta
 

pvlib/tests/iotools/test_pvgis.py

@@ -447,7 +447,7 @@ def test_get_pvgis_tmy_coerce_year():
     cet_tz = 1  # Turin time is CET
     cet_name = 'Etc/GMT-1'
     # check indices of rolled data after converting timezone
-    pvgis_data, _, _, _ = get_pvgis_tmy(45, 8, utc_offset=cet_tz)
+    pvgis_data, _, _, _ = get_pvgis_tmy(45, 8, roll_utc_offset=cet_tz)
     jan1_midnight = pd.Timestamp('1990-01-01 00:00:00', tz=cet_name)
     dec31_midnight = pd.Timestamp('1990-12-31 23:00:00', tz=cet_name)
     assert pvgis_data.index[0] == jan1_midnight
@@ -459,14 +459,23 @@ def test_get_pvgis_tmy_coerce_year():
     # repeat tests with year coerced
     test_yr = 2021
     pvgis_data, _, _, _ = get_pvgis_tmy(
-        45, 8, utc_offset=cet_tz, coerce_year=test_yr)
+        45, 8, roll_utc_offset=cet_tz, coerce_year=test_yr)
     jan1_midnight = pd.Timestamp(f'{test_yr}-01-01 00:00:00', tz=cet_name)
     dec31_midnight = pd.Timestamp(f'{test_yr}-12-31 23:00:00', tz=cet_name)
     assert pvgis_data.index[0] == jan1_midnight
     assert pvgis_data.index[-1] == dec31_midnight
     for m, test_case in enumerate(noon_test_data):
         expected = pvgis_data[pvgis_data.index.month == m+1].iloc[12+cet_tz]
         assert all(test_case == expected)
+    # repeat tests with year coerced but utc offset none or zero
+    pvgis_data, _, _, _ = get_pvgis_tmy(45, 8, coerce_year=test_yr)
+    jan1_midnight = pd.Timestamp(f'{test_yr}-01-01 00:00:00', tz='UTC')
+    dec31_midnight = pd.Timestamp(f'{test_yr}-12-31 23:00:00', tz='UTC')
+    assert pvgis_data.index[0] == jan1_midnight
+    assert pvgis_data.index[-1] == dec31_midnight
+    for m, test_case in enumerate(noon_test_data):
+        expected = pvgis_data[pvgis_data.index.month == m+1].iloc[12]
+        assert all(test_case == expected)
 
 
 @pytest.mark.remote_data