All classes and methods in dates support both string and tzinfo as tz-argument

Oscar Gustafsson · Oscar Gustafsson · commit d51b377c1a7e · 2022-01-12T16:11:16.000+01:00
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -82,11 +82,12 @@
      In [1]: date(2006, 4, 1).toordinal() - date(1, 1, 1).toordinal()
      Out[1]: 732401
 
-All the Matplotlib date converters, tickers and formatters are timezone aware.
-If no explicit timezone is provided, :rc:`timezone` is assumed.  If you want to
-use a custom time zone, pass a `datetime.tzinfo` instance with the tz keyword
-argument to `num2date`, `.Axis.axis_date`, and any custom date tickers or
-locators you create.
+All the Matplotlib date converters, tickers and formatters are time-zone aware.
+If no explicit time zone is provided, :rc:`timezone` is assumed, provided as a
+string.  If you want to use a custom time zone, pass a `datetime.tzinfo`
+instance or a string with the time-zone name with the tz keyword argument to
+`num2date`, `.Axis.axis_date`, and any custom date tickers or locators you
+create. Time-zone strings are parsed by `~dateutil.tz.gettz`.
 
 A wide range of specific and general purpose date tick locators and
 formatters are provided in this module.  See
@@ -202,12 +203,24 @@
 UTC = datetime.timezone.utc
 
 
-def _get_rc_timezone():
-    """Retrieve the preferred timezone from the rcParams dictionary."""
-    s = mpl.rcParams['timezone']
-    if s == 'UTC':
-        return UTC
-    return dateutil.tz.gettz(s)
+def _get_tzinfo(tz=None):
+    """
+    Generate tzinfo from a string or return tzinfo. If None (default),
+    retrieve the preferred time zone from the rcParams dictionary.
+    """
+    if tz is None:
+        tz = mpl.rcParams['timezone']
+        if tz == 'UTC':
+            return UTC
+    if isinstance(tz, str):
+        tzinfo = dateutil.tz.gettz(tz)
+        if tzinfo is None:
+            raise ValueError(f"{tz} is not a valid time zone as parsed by"
+                             " dateutil.tz.gettz.")
+        return tzinfo
+    if isinstance(tz, datetime.tzinfo):
+        return tz
+    raise TypeError("tz must be string or tzinfo subclass.")
 
 
 """
@@ -337,12 +350,11 @@ def _from_ordinalf(x, tz=None):
 
     The input date *x* is a float in ordinal days at UTC, and the output will
     be the specified `.datetime` object corresponding to that time in
-    timezone *tz*, or if *tz* is ``None``, in the timezone specified in
+    time zone *tz*, or if *tz* is ``None``, in the time zone specified in
     :rc:`timezone`.
     """
 
-    if tz is None:
-        tz = _get_rc_timezone()
+    tz = _get_tzinfo(tz)
 
     dt = (np.datetime64(get_epoch()) +
           np.timedelta64(int(np.round(x * MUSECONDS_PER_DAY)), 'us'))
@@ -355,7 +367,7 @@ def _from_ordinalf(x, tz=None):
 
     # datetime64 is always UTC:
     dt = dt.replace(tzinfo=dateutil.tz.gettz('UTC'))
-    # but maybe we are working in a different timezone so move.
+    # but maybe we are working in a different time zone so move.
     dt = dt.astimezone(tz)
     # fix round off errors
     if np.abs(x) > 70 * 365:
@@ -508,13 +520,13 @@ def num2date(x, tz=None):
         Number of days (fraction part represents hours, minutes, seconds)
         since the epoch.  See `.get_epoch` for the
         epoch, which can be changed by :rc:`date.epoch` or `.set_epoch`.
-    tz : str, default: :rc:`timezone`
-        Timezone of *x*.
+    tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+        Time zone of *x*. If a string, *tz* is passed to `dateutil.tz`.
 
     Returns
     -------
     `~datetime.datetime` or sequence of `~datetime.datetime`
-        Dates are returned in timezone *tz*.
+        Dates are returned in time zone *tz*.
 
         If *x* is a sequence, a sequence of `~datetime.datetime` objects will
         be returned.
@@ -525,8 +537,7 @@ def num2date(x, tz=None):
     Gregorian calendar is assumed; this is not universal practice.
     For details, see the module docstring.
     """
-    if tz is None:
-        tz = _get_rc_timezone()
+    tz = _get_tzinfo(tz)
     return _from_ordinalf_np_vectorized(x, tz).tolist()
 
 
@@ -621,16 +632,14 @@ def __init__(self, fmt, tz=None, *, usetex=None):
         ----------
         fmt : str
             `~datetime.datetime.strftime` format string
-        tz : `datetime.tzinfo`, default: :rc:`timezone`
-            Ticks timezone.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks time zone.
         usetex : bool, default: :rc:`text.usetex`
             To enable/disable the use of TeX's math mode for rendering the
             results of the formatter.
         """
-        if tz is None:
-            tz = _get_rc_timezone()
+        self.tz = _get_tzinfo(tz)
         self.fmt = fmt
-        self.tz = tz
         self._usetex = (usetex if usetex is not None else
                         mpl.rcParams['text.usetex'])
 
@@ -639,7 +648,7 @@ def __call__(self, x, pos=0):
         return _wrap_in_tex(result) if self._usetex else result
 
     def set_tzinfo(self, tz):
-        self.tz = tz
+        self.tz = _get_tzinfo(tz)
 
 
 class ConciseDateFormatter(ticker.Formatter):
@@ -656,8 +665,8 @@ class ConciseDateFormatter(ticker.Formatter):
     locator : `.ticker.Locator`
         Locator that this axis is using.
 
-    tz : str, optional
-        Passed to `.dates.date2num`.
+    tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+        Passed to `.dates.num2date`.
 
     formats : list of 6 strings, optional
         Format strings for 6 levels of tick labelling: mostly years,
@@ -757,7 +766,7 @@ def __init__(self, locator, tz=None, formats=None, offset_formats=None,
 
         if offset_formats:
             if len(offset_formats) != 6:
-                raise ValueError('offsetfmts argument must be a list of '
+                raise ValueError('offset_formats argument must be a list of '
                                  '6 format strings (or None)')
             self.offset_formats = offset_formats
         else:
@@ -927,8 +936,8 @@ def __init__(self, locator, tz=None, defaultfmt='%Y-%m-%d', *,
         locator : `.ticker.Locator`
             Locator that this axis is using.
 
-        tz : str, optional
-            Passed to `.dates.date2num`.
+        tz : str or `~datetime.tzinfo`, optional
+            Passed to `.dates.num2date`.
 
         defaultfmt : str
             The default format to use if none of the values in ``self.scaled``
@@ -1001,7 +1010,7 @@ def _update_rrule(self, **kwargs):
         tzinfo = self._base_tzinfo
 
         # rrule does not play nicely with time zones - especially pytz time
-        # zones, it's best to use naive zones and attach timezones once the
+        # zones, it's best to use naive zones and attach time zones once the
         # datetimes are returned
         if 'dtstart' in kwargs:
             dtstart = kwargs['dtstart']
@@ -1103,17 +1112,15 @@ def __init__(self, tz=None):
         """
         Parameters
         ----------
-        tz : `datetime.tzinfo`
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
         """
-        if tz is None:
-            tz = _get_rc_timezone()
-        self.tz = tz
+        self.tz = _get_tzinfo(tz)
 
     def set_tzinfo(self, tz):
         """
-        Set time zone info.
+        Set time zone info. str or `~datetime.tzinfo`.
         """
-        self.tz = tz
+        self.tz = _get_tzinfo(tz)
 
     def datalim_to_dt(self):
         """Convert axis data interval to datetime objects."""
@@ -1283,8 +1290,8 @@ def __init__(self, tz=None, minticks=5, maxticks=None,
         """
         Parameters
         ----------
-        tz : `datetime.tzinfo`
-            Ticks timezone.
+        tz : str or `~datetime.tzinfo`, default: :rc:`timezone`
+            Ticks time zone.
         minticks : int
             The minimum number of ticks desired; controls whether ticks occur
             yearly, monthly, etc.
@@ -1303,7 +1310,7 @@ def __init__(self, tz=None, minticks=5, maxticks=None,
             the ticks to be at hours 0, 6, 12, 18 when hourly ticking is done
             at 6 hour intervals.
         """
-        super().__init__(tz)
+        super().__init__(tz=tz)
         self._freq = YEARLY
         self._freqs = [YEARLY, MONTHLY, DAILY, HOURLY, MINUTELY,
                        SECONDLY, MICROSECONDLY]
@@ -1457,7 +1464,7 @@ def get_locator(self, dmin, dmax):
                                  byhour=byhour, byminute=byminute,
                                  bysecond=bysecond)
 
-            locator = RRuleLocator(rrule, self.tz)
+            locator = RRuleLocator(rrule, tz=self.tz)
         else:
             locator = MicrosecondLocator(interval, tz=self.tz)
             if date2num(dmin) > 70 * 365 and interval < 1000:
@@ -1490,7 +1497,7 @@ def __init__(self, base=1, month=1, day=1, tz=None):
         """
         rule = rrulewrapper(YEARLY, interval=base, bymonth=month,
                             bymonthday=day, **self.hms0d)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
         self.base = ticker._Edge_integer(base, 0)
 
     def _create_rrule(self, vmin, vmax):
@@ -1534,7 +1541,7 @@ def __init__(self, bymonth=None, bymonthday=1, interval=1, tz=None):
 
         rule = rrulewrapper(MONTHLY, bymonth=bymonth, bymonthday=bymonthday,
                             interval=interval, **self.hms0d)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class WeekdayLocator(RRuleLocator):
@@ -1562,7 +1569,7 @@ def __init__(self, byweekday=1, interval=1, tz=None):
 
         rule = rrulewrapper(DAILY, byweekday=byweekday,
                             interval=interval, **self.hms0d)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class DayLocator(RRuleLocator):
@@ -1588,7 +1595,7 @@ def __init__(self, bymonthday=None, interval=1, tz=None):
 
         rule = rrulewrapper(DAILY, bymonthday=bymonthday,
                             interval=interval, **self.hms0d)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class HourLocator(RRuleLocator):
@@ -1608,7 +1615,7 @@ def __init__(self, byhour=None, interval=1, tz=None):
 
         rule = rrulewrapper(HOURLY, byhour=byhour, interval=interval,
                             byminute=0, bysecond=0)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class MinuteLocator(RRuleLocator):
@@ -1628,7 +1635,7 @@ def __init__(self, byminute=None, interval=1, tz=None):
 
         rule = rrulewrapper(MINUTELY, byminute=byminute, interval=interval,
                             bysecond=0)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class SecondLocator(RRuleLocator):
@@ -1648,7 +1655,7 @@ def __init__(self, bysecond=None, interval=1, tz=None):
             bysecond = range(60)
 
         rule = rrulewrapper(SECONDLY, bysecond=bysecond, interval=interval)
-        super().__init__(rule, tz)
+        super().__init__(rule, tz=tz)
 
 
 class MicrosecondLocator(DateLocator):
diff --git a/lib/matplotlib/tests/test_dates.py b/lib/matplotlib/tests/test_dates.py
@@ -446,6 +446,9 @@ def _create_auto_date_locator(date1, date2):
     locator = mdates.AutoDateLocator(interval_multiples=False)
     assert locator.maxticks == {0: 11, 1: 12, 3: 11, 4: 12, 5: 11, 6: 11, 7: 8}
 
+    locator = mdates.AutoDateLocator(maxticks={dateutil.rrule.MONTHLY: 5})
+    assert locator.maxticks == {0: 11, 1: 5, 3: 11, 4: 12, 5: 11, 6: 11, 7: 8}
+
     locator = mdates.AutoDateLocator(maxticks=5)
     assert locator.maxticks == {0: 5, 1: 5, 3: 5, 4: 5, 5: 5, 6: 5, 7: 5}
 
@@ -1234,14 +1237,50 @@ def test_julian2num():
     assert mdates.num2julian(2.0) == 2440589.5
 
 
-def test_rcparams_timezone():
-    assert mdates._get_rc_timezone() == mdates.UTC
-    tz = 'Europe/Iceland'
-    assert mdates._get_rc_timezone() != dateutil.tz.gettz(tz)
+def test_DateLocator():
+    locator = mdates.DateLocator()
+    # Test nonsingular
+    assert locator.nonsingular(0, np.inf) == (10957.0, 14610.0)
+    assert locator.nonsingular(0, 1) == (0, 1)
+    assert locator.nonsingular(1, 0) == (0, 1)
+    assert locator.nonsingular(0, 0) == (-2, 2)
+    locator.create_dummy_axis()
+    # default values
+    assert locator.datalim_to_dt() == (
+        datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
+        datetime.datetime(1970, 1, 2, 0, 0, tzinfo=datetime.timezone.utc))
+
+    # Check default is UTC
+    assert locator.tz == mdates.UTC
+    tz_str = 'Iceland'
+    iceland_tz = dateutil.tz.gettz(tz_str)
+    # Check not Iceland
+    assert locator.tz != iceland_tz
+    # Set it to to Iceland
+    locator.set_tzinfo('Iceland')
+    # Check now it is Iceland
+    assert locator.tz == iceland_tz
+    locator.create_dummy_axis()
+    locator.axis.set_data_interval(*mdates.date2num(["2022-01-10",
+                                                     "2022-01-08"]))
+    assert locator.datalim_to_dt() == (
+        datetime.datetime(2022, 1, 8, 0, 0, tzinfo=iceland_tz),
+        datetime.datetime(2022, 1, 10, 0, 0, tzinfo=iceland_tz))
+
+    # Set rcParam
+    plt.rcParams['timezone'] = tz_str
 
-    plt.rcParams['timezone'] = tz
+    # Create a new one in a similar way
+    locator = mdates.DateLocator()
+    # Check now it is Iceland
+    assert locator.tz == iceland_tz
 
-    assert mdates._get_rc_timezone() == dateutil.tz.gettz(tz)
+    # Test invalid tz values
+    with pytest.raises(ValueError, match="Aiceland is not a valid time zone"):
+        mdates.DateLocator(tz="Aiceland")
+    with pytest.raises(TypeError,
+                       match="tz must be string or tzinfo subclass."):
+        mdates.DateLocator(tz=1)
 
 
 def test_datestr2num():
@@ -1258,13 +1297,15 @@ def test_datestr2num():
 
 def test_concise_formatter_exceptions():
     locator = mdates.AutoDateLocator()
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match="formats argument must be a list"):
         mdates.ConciseDateFormatter(locator, formats=['', '%Y'])
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError,
+                       match="zero_formats argument must be a list"):
         mdates.ConciseDateFormatter(locator, zero_formats=['', '%Y'])
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError,
+                       match="offset_formats argument must be a list"):
         mdates.ConciseDateFormatter(locator, offset_formats=['', '%Y'])
 
 
@@ -1275,15 +1316,13 @@ def test_concise_formatter_call():
     assert formatter.format_data_short(19002.0) == '2022-01-10 00:00:00'
 
 
-def test_date_ticker_factory():
-    data = (
-        (0.02, mdates.MinuteLocator),
-        (1, mdates.HourLocator),
-        (19, mdates.DayLocator),
-        (40, mdates.WeekdayLocator),
-        (200, mdates.MonthLocator),
-        (2000, mdates.YearLocator),
-        )
-    for span, expected_locator in data:
-        locator, _ = mdates.date_ticker_factory(span)
-        assert isinstance(locator, expected_locator)
+@pytest.mark.parametrize('span, expected_locator',
+                         ((0.02, mdates.MinuteLocator),
+                          (1, mdates.HourLocator),
+                          (19, mdates.DayLocator),
+                          (40, mdates.WeekdayLocator),
+                          (200, mdates.MonthLocator),
+                          (2000, mdates.YearLocator)))
+def test_date_ticker_factory(span, expected_locator):
+    locator, _ = mdates.date_ticker_factory(span)
+    assert isinstance(locator, expected_locator)
