pvlib 0.11.1__py3-none-any.whl → 0.12.0__py3-none-any.whl

pvlib/location.py

@@ -6,6 +6,7 @@ This module contains the Location class.
 
 import pathlib
 import datetime
+import zoneinfo
 
 import pandas as pd
 import pytz
@@ -18,13 +19,16 @@ from pvlib.tools import _degrees_to_index
 class Location:
     """
     Location objects are convenient containers for latitude, longitude,
-    timezone, and altitude data associated with a particular
-    geographic location. You can also assign a name to a location object.
+    time zone, and altitude data associated with a particular geographic
+    location. You can also assign a name to a location object.
 
-    Location objects have two timezone attributes:
+    Location objects have two time-zone attributes:
 
-        * ``tz`` is a IANA timezone string.
-        * ``pytz`` is a pytz timezone object.
+        * ``tz`` is an IANA time-zone string.
+        * ``pytz`` is a pytz-based time-zone object (read only).
+
+    The read-only ``pytz`` attribute will stay in sync with any changes made
+    using ``tz``.
 
     Location objects support the print method.
 
@@ -38,12 +42,16 @@ class Location:
         Positive is east of the prime meridian.
         Use decimal degrees notation.
 
-    tz : str, int, float, or pytz.timezone, default 'UTC'.
-        See
-        http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-        for a list of valid time zones.
-        pytz.timezone objects will be converted to strings.
-        ints and floats must be in hours from UTC.
+    tz : time zone as str, int, float, or datetime.tzinfo, default 'UTC'.
+        See http://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a
+        list of valid name strings. An `int` or `float` must be a whole-number
+        hour offsets from UTC that can be converted to the IANA-supported
+        'Etc/GMT-N' format. (Note the limited range of the offset N and its
+        sign-change convention.) Time zones from the pytz and zoneinfo packages
+        may also be passed here, as they are subclasses of datetime.tzinfo.
+
+        The `tz` attribute is represented as a valid IANA time zone name
+        string.
 
     altitude : float, optional
         Altitude from sea level in meters.
@@ -54,43 +62,75 @@ class Location:
     name : string, optional
         Sets the name attribute of the Location object.
 
+    Raises
+    ------
+    ValueError
+        when the time zone ``tz`` cannot be converted.
+
+    zoneinfo.ZoneInfoNotFoundError
+        when the time zone ``tz`` is not recognizable as an IANA time zone by
+        the ``zoneinfo.ZoneInfo`` initializer used for internal time-zone
+        representation.
+
     See also
     --------
     pvlib.pvsystem.PVSystem
     """
 
-    def __init__(self, latitude, longitude, tz='UTC', altitude=None,
-                 name=None):
-
+    def __init__(
+        self, latitude, longitude, tz='UTC', altitude=None, name=None
+    ):
         self.latitude = latitude
         self.longitude = longitude
-
-        if isinstance(tz, str):
-            self.tz = tz
-            self.pytz = pytz.timezone(tz)
-        elif isinstance(tz, datetime.timezone):
-            self.tz = 'UTC'
-            self.pytz = pytz.UTC
-        elif isinstance(tz, datetime.tzinfo):
-            self.tz = tz.zone
-            self.pytz = tz
-        elif isinstance(tz, (int, float)):
-            self.tz = tz
-            self.pytz = pytz.FixedOffset(tz*60)
-        else:
-            raise TypeError('Invalid tz specification')
+        self.tz = tz
 
         if altitude is None:
             altitude = lookup_altitude(latitude, longitude)
 
         self.altitude = altitude
-
         self.name = name
 
     def __repr__(self):
         attrs = ['name', 'latitude', 'longitude', 'altitude', 'tz']
+        # Use None as getattr default in case __repr__ is called during
+        # initialization before all attributes have been assigned.
         return ('Location: \n  ' + '\n  '.join(
-            f'{attr}: {getattr(self, attr)}' for attr in attrs))
+            f'{attr}: {getattr(self, attr, None)}' for attr in attrs))
+
+    @property
+    def tz(self):
+        """The location's IANA time-zone string."""
+        return str(self._zoneinfo)
+
+    @tz.setter
+    def tz(self, tz_):
+        # self._zoneinfo holds single source of time-zone truth as IANA name.
+        if isinstance(tz_, str):
+            self._zoneinfo = zoneinfo.ZoneInfo(tz_)
+        elif isinstance(tz_, int):
+            self._zoneinfo = zoneinfo.ZoneInfo(f"Etc/GMT{-tz_:+d}")
+        elif isinstance(tz_, float):
+            if tz_ % 1 != 0:
+                raise TypeError(
+                    "Floating-point tz has non-zero fractional part: "
+                    f"{tz_}. Only whole-number offsets are supported."
+                )
+
+            self._zoneinfo = zoneinfo.ZoneInfo(f"Etc/GMT{-int(tz_):+d}")
+        elif isinstance(tz_, datetime.tzinfo):
+            # Includes time zones generated by pytz and zoneinfo packages.
+            self._zoneinfo = zoneinfo.ZoneInfo(str(tz_))
+        else:
+            raise TypeError(
+                f"invalid tz specification: {tz_}, must be an IANA time zone "
+                "string, a whole-number int/float UTC offset, or a "
+                "datetime.tzinfo object (including subclasses)"
+            )
+
+    @property
+    def pytz(self):
+        """The location's pytz time zone (read only)."""
+        return pytz.timezone(str(self._zoneinfo))
 
     @classmethod
     def from_tmy(cls, tmy_metadata, tmy_data=None, **kwargs):
@@ -328,7 +368,7 @@ class Location:
 
         return airmass
 
-    def get_sun_rise_set_transit(self, times, method='pyephem', **kwargs):
+    def get_sun_rise_set_transit(self, times, method='spa', **kwargs):
         """
         Calculate sunrise, sunset and transit times.
 
@@ -336,7 +376,7 @@ class Location:
         ----------
         times : DatetimeIndex
             Must be localized to the Location
-        method : str, default 'pyephem'
+        method : str, default 'spa'
             'pyephem', 'spa', or 'geometric'
 
         kwargs :

pvlib/modelchain.py

@@ -29,7 +29,7 @@ POA_KEYS = ('poa_global', 'poa_direct', 'poa_diffuse')
 
 # Optional keys to communicate temperature data. If provided,
 # 'cell_temperature' overrides ModelChain.temperature_model and sets
-# ModelChain.cell_temperature to the data. If 'module_temperature' is provdied,
+# ModelChain.cell_temperature to the data. If 'module_temperature' is provided,
 # overrides ModelChain.temperature_model with
 # pvlib.temperature.sapm_celL_from_module
 TEMPERATURE_KEYS = ('module_temperature', 'cell_temperature')
@@ -253,7 +253,7 @@ class ModelChainResult:
         def _head(obj):
             try:
                 return obj[:3]
-            except:
+            except Exception:
                 return obj
 
         if type(self.dc) is tuple:
@@ -269,7 +269,7 @@ class ModelChainResult:
                  '\n')
         lines = []
         for attr in mc_attrs:
-            if not (attr.startswith('_') or attr=='times'):
+            if not (attr.startswith('_') or attr == 'times'):
                 lines.append(f' {attr}: ' + _mcr_repr(getattr(self, attr)))
         desc4 = '\n'.join(lines)
         return (desc1 + desc2 + desc3 + desc4)
@@ -330,12 +330,15 @@ class ModelChain:
         'interp' and 'no_loss'. The ModelChain instance will be passed as the
         first argument to a user-defined function.
 
-    spectral_model : str, or function, optional
-        If not specified, the model will be inferred from the parameters that
-        are common to all of system.arrays[i].module_parameters.
-        Valid strings are 'sapm', 'first_solar', 'no_loss'.
+    spectral_model : str or function, optional
+        Valid strings are:
+
+        - ``'sapm'``
+        - ``'first_solar'``
+        - ``'no_loss'``
+
         The ModelChain instance will be passed as the first argument to
-        a user-defined function.
+        a user-defined function. If not specified, ``'no_loss'`` is assumed.
 
     temperature_model : str or function, optional
         Valid strings are: 'sapm', 'pvsyst', 'faiman', 'fuentes', 'noct_sam'.
@@ -386,7 +389,6 @@ class ModelChain:
 
         self.results = ModelChainResult()
 
-
     @classmethod
     def with_pvwatts(cls, system, location,
                      clearsky_model='ineichen',
@@ -855,9 +857,7 @@ class ModelChain:
 
     @spectral_model.setter
     def spectral_model(self, model):
-        if model is None:
-            self._spectral_model = self.infer_spectral_model()
-        elif isinstance(model, str):
+        if isinstance(model, str):
             model = model.lower()
             if model == 'first_solar':
                 self._spectral_model = self.first_solar_spectral_loss
@@ -867,30 +867,12 @@ class ModelChain:
                 self._spectral_model = self.no_spectral_loss
             else:
                 raise ValueError(model + ' is not a valid spectral loss model')
-        else:
+        elif model is None:
+            # not setting a model is equivalent to setting no_loss
+            self._spectral_model = self.no_spectral_loss
+        else:  # assume model is callable with 1st argument = the MC instance
             self._spectral_model = partial(model, self)
 
-    def infer_spectral_model(self):
-        """Infer spectral model from system attributes."""
-        module_parameters = tuple(
-            array.module_parameters for array in self.system.arrays)
-        params = _common_keys(module_parameters)
-        if {'A4', 'A3', 'A2', 'A1', 'A0'} <= params:
-            return self.sapm_spectral_loss
-        elif ((('Technology' in params or
-                'Material' in params) and
-               (self.system._infer_cell_type() is not None)) or
-              'first_solar_spectral_coefficients' in params):
-            return self.first_solar_spectral_loss
-        else:
-            raise ValueError('could not infer spectral model from '
-                             'system.arrays[i].module_parameters. Check that '
-                             'the module_parameters for all Arrays in '
-                             'system.arrays contain valid '
-                             'first_solar_spectral_coefficients, a valid '
-                             'Material or Technology value, or set '
-                             'spectral_model="no_loss".')
-
     def first_solar_spectral_loss(self):
         self.results.spectral_modifier = self.system.first_solar_spectral_loss(
             _tuple_from_dfs(self.results.weather, 'precipitable_water'),
@@ -1570,7 +1552,7 @@ class ModelChain:
         ----------
         data : DataFrame
             May contain columns ``'cell_temperature'`` or
-            ``'module_temperaure'``.
+            ``'module_temperature'``.
 
         Returns
         -------
@@ -1679,6 +1661,7 @@ class ModelChain:
         self.prepare_inputs(weather)
         self.aoi_model()
         self.spectral_model()
+
         self.effective_irradiance_model()
 
         self._run_from_effective_irrad(weather)