ENH: to_datetime support iso week year (16607) Updated

doc/source/whatsnew/v0.24.0.rst

@@ -362,6 +362,7 @@ See the :ref:`Advanced documentation on renaming<advanced.index_names>` for more
 Other Enhancements
 ^^^^^^^^^^^^^^^^^^
 
+- Added support for %G strptime directive in parsing datetimes
 - :func:`merge` now directly allows merge between objects of type ``DataFrame`` and named ``Series``, without the need to convert the ``Series`` object into a ``DataFrame`` beforehand (:issue:`21220`)
 - ``ExcelWriter`` now accepts ``mode`` as a keyword argument, enabling append to existing workbooks when using the ``openpyxl`` engine (:issue:`3441`)
 - ``FrozenList`` has gained the ``.union()`` and ``.difference()`` methods. This functionality greatly simplifies groupby's that rely on explicitly excluding certain columns. See :ref:`Splitting an object into groups <groupby.split>` for more information (:issue:`15475`, :issue:`15506`).

pandas/_libs/tslibs/strptime.pyx

@@ -54,7 +54,10 @@ cdef dict _parse_code_table = {'y': 0,
                                'W': 16,
                                'Z': 17,
                                'p': 18,  # an additional key, only with I
-                               'z': 19}
+                               'z': 19,
+                               'G': 20,
+                               'V': 21,
+                               'u': 22}
 
 
 def array_strptime(object[:] values, object fmt,
@@ -76,7 +79,8 @@ def array_strptime(object[:] values, object fmt,
         int64_t[:] iresult
         object[:] result_timezone
         int year, month, day, minute, hour, second, weekday, julian
-        int week_of_year, week_of_year_start, parse_code, ordinal
+        int week_of_year, week_of_year_start, parse_code, ordinal, 
+            iso_week, iso_year
         int64_t us, ns
         object val, group_key, ampm, found, timezone
         dict found_key
@@ -169,13 +173,14 @@ def array_strptime(object[:] values, object fmt,
                 raise ValueError("time data %r does not match format "
                                  "%r (search)" % (values[i], fmt))
 
+        iso_year = -1
         year = 1900
         month = day = 1
         hour = minute = second = ns = us = 0
         timezone = None
         # Default to -1 to signify that values not known; not critical to have,
         # though
-        week_of_year = -1
+        iso_week = week_of_year = -1
         week_of_year_start = -1
         # weekday and julian defaulted to -1 so as to signal need to calculate
         # values
@@ -265,13 +270,43 @@ def array_strptime(object[:] values, object fmt,
                 timezone = pytz.timezone(found_dict['Z'])
             elif parse_code == 19:
                 timezone = parse_timezone_directive(found_dict['z'])
+            elif parse_code == 20:
+                iso_year = int(found_dict['G'])
+            elif parse_code == 21:
+                iso_week = int(found_dict['V'])
+            elif parse_code == 22:
+                weekday = int(found_dict['u'])
+                weekday -= 1
+
+        # don't assume default values for ISO week/year
+        if iso_year != -1:
+            if iso_week == -1 or weekday == -1:
+                raise ValueError("ISO year directive '%G' must be used with "
+                                 "the ISO week directive '%V' and a weekday "
+                                 "directive '%A', '%a', '%w', or '%u'.")
+            if julian != -1:
+                raise ValueError("Day of the year directive '%j' is not "
+                                 "compatible with ISO year directive '%G'. "
+                                 "Use '%Y' instead.")
+        elif year != -1 and week_of_year == -1 and iso_week != -1:
+            if weekday == -1:
+                raise ValueError("ISO week directive '%V' must be used with "
+                                 "the ISO year directive '%G' and a weekday "
+                                 "directive '%A', '%a', '%w', or '%u'.")
+            else:
+                raise ValueError("ISO week directive '%V' is incompatible with"
+                                 " the year directive '%Y'. Use the ISO year "
+                                 "'%G' instead.")
 
         # If we know the wk of the year and what day of that wk, we can figure
         # out the Julian day of the year.
-        if julian == -1 and week_of_year != -1 and weekday != -1:
-            week_starts_Mon = True if week_of_year_start == 0 else False
-            julian = _calc_julian_from_U_or_W(year, week_of_year, weekday,
-                                              week_starts_Mon)
+        if julian == -1 and weekday != -1:
+            if week_of_year != -1:
+                week_starts_Mon = True if week_of_year_start == 0 else False
+                julian = _calc_julian_from_U_or_W(year, week_of_year, weekday,
+                                                  week_starts_Mon)
+            elif iso_year != -1 and iso_week != -1:
+                year, julian = _calc_julian_from_V(iso_year, iso_week, weekday + 1)
         # Cannot pre-calculate datetime_date() since can change in Julian
         # calculation and thus could have different value for the day of the wk
         # calculation.
@@ -511,14 +546,17 @@ class TimeRE(dict):
             # The " \d" part of the regex is to make %c from ANSI C work
             'd': r"(?P<d>3[0-1]|[1-2]\d|0[1-9]|[1-9]| [1-9])",
             'f': r"(?P<f>[0-9]{1,9})",
+            'G': r"(?P<G>\d\d\d\d)",
             'H': r"(?P<H>2[0-3]|[0-1]\d|\d)",
             'I': r"(?P<I>1[0-2]|0[1-9]|[1-9])",
             'j': (r"(?P<j>36[0-6]|3[0-5]\d|[1-2]\d\d|0[1-9]\d|00[1-9]|"
                   r"[1-9]\d|0[1-9]|[1-9])"),
             'm': r"(?P<m>1[0-2]|0[1-9]|[1-9])",
             'M': r"(?P<M>[0-5]\d|\d)",
             'S': r"(?P<S>6[0-1]|[0-5]\d|\d)",
+            'u': r"(?P<u>[1-7])",
             'U': r"(?P<U>5[0-3]|[0-4]\d|\d)",
+            'V': r"(?P<V>5[0-3]|0[1-9]|[1-4]\d|\d)",
             'w': r"(?P<w>[0-6])",
             # W is set below by using 'U'
             'y': r"(?P<y>\d\d)",
@@ -620,6 +658,25 @@ cdef _calc_julian_from_U_or_W(int year, int week_of_year,
         return 1 + days_to_week + day_of_week
 
 
+cdef _calc_julian_from_V(int iso_year, int iso_week, int iso_weekday):
+    """Calculate the Julian day based on the ISO 8601 year, week, and weekday.
+    ISO weeks start on Mondays, with week 01 being the week containing 4 Jan.
+    ISO week days range from 1 (Monday) to 7 (Sunday)."""
+
+    cdef:
+        int correction, ordinal
+
+    correction = datetime_date(iso_year, 1, 4).isoweekday() + 3
+    ordinal = (iso_week * 7) + iso_weekday - correction
+    # ordinal may be negative or 0 now, which means the date is in the previous
+    # calendar year
+    if ordinal < 1:
+        ordinal += datetime_date(iso_year, 1, 1).toordinal()
+        iso_year -= 1
+        ordinal -= datetime_date(iso_year, 1, 1).toordinal()
+    return iso_year, ordinal
+
+
 cdef parse_timezone_directive(object z):
     """
     Parse the '%z' directive and return a pytz.FixedOffset

pandas/tests/indexes/datetimes/test_tools.py

@@ -247,6 +247,53 @@ def test_to_datetime_parse_timezone_keeps_name(self):
 
 
 class TestToDatetime(object):
+    @pytest.mark.parametrize("s, _format, dt", [
+        ['2015-1-1', '%G-%V-%u', datetime(2014, 12, 29, 0, 0)],
+        ['2015-1-4', '%G-%V-%u', datetime(2015, 1, 1, 0, 0)],
+        ['2015-1-7', '%G-%V-%u', datetime(2015, 1, 4, 0, 0)]
+    ])
+    def test_to_datetime_iso_week_year_format(self, s, _format, dt):
+        assert to_datetime(s, format=_format) == dt
+
+    @pytest.mark.parametrize("msg, s, _format", [
+        ["ISO week directive '%V' must be used with the ISO year directive "
+         "'%G' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 50",
+         "%Y %V"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 51",
+         "%G %V"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 "
+         "Monday", "%G %A"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 Mon",
+         "%G %a"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 6",
+         "%G %w"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "1999 6",
+         "%G %u"],
+        ["ISO year directive '%G' must be used with the ISO week directive "
+         "'%V' and a weekday directive '%A', '%a', '%w', or '%u'.", "2051",
+         "%G"],
+        ["Day of the year directive '%j' is not compatible with ISO year "
+         "directive '%G'. Use '%Y' instead.", "1999 51 6 256", "%G %V %u %j"],
+        ["ISO week directive '%V' is incompatible with the year directive "
+         "'%Y'. Use the ISO year '%G' instead.", "1999 51 Sunday", "%Y %V %A"],
+        ["ISO week directive '%V' is incompatible with the year directive "
+         "'%Y'. Use the ISO year '%G' instead.", "1999 51 Sun", "%Y %V %a"],
+        ["ISO week directive '%V' is incompatible with the year directive "
+         "'%Y'. Use the ISO year '%G' instead.", "1999 51 1", "%Y %V %w"],
+        ["ISO week directive '%V' is incompatible with the year directive "
+         "'%Y'. Use the ISO year '%G' instead.", "1999 51 1", "%Y %V %u"],
+        ["ISO week directive '%V' must be used with the ISO year directive "
+         "'%G' and a weekday directive '%A', '%a', '%w', or '%u'.", "20", "%V"]
+    ])
+    def test_ValueError_iso_week_year(self, msg, s, _format):
+        with pytest.raises(ValueError, message=msg):
+            to_datetime(s, format=_format)
+
     @pytest.mark.parametrize('tz', [None, 'US/Central'])
     def test_to_datetime_dtarr(self, tz):
         # DatetimeArray