Add function to get_iso_calendar

- This function reproduces what `datetime.date.isocalendar` returns
- Refactor get_week_of_year to use get_iso_calendar internally

Author: mgmarino

pandas/_libs/tslibs/ccalendar.pxd

@@ -7,4 +7,5 @@ cdef int dayofweek(int y, int m, int d) nogil
 cdef bint is_leapyear(int64_t year) nogil
 cpdef int32_t get_days_in_month(int year, Py_ssize_t month) nogil
 cpdef int32_t get_week_of_year(int year, int month, int day) nogil
+cpdef (int32_t, int32_t, int32_t) get_iso_calendar(int year, int month, int day) nogil
 cpdef int32_t get_day_of_year(int year, int month, int day) nogil

pandas/_libs/tslibs/ccalendar.pyx

@@ -150,33 +150,63 @@ cpdef int32_t get_week_of_year(int year, int month, int day) nogil:
     -------
     week_of_year : int32_t
 
+    Notes
+    -----
+    Assumes the inputs describe a valid date.
+    """
+    return get_iso_calendar(year, month, day)[1]
+
+
+@cython.wraparound(False)
+@cython.boundscheck(False)
+cpdef (int32_t, int32_t, int32_t) get_iso_calendar(int year, int month, int day) nogil:
+    """
+    Return the year, week, and day of year corresponding to ISO 8601
+
+    Parameters
+    ----------
+    year : int
+    month : int
+    day : int
+
+    Returns
+    -------
+    (year : int32_t, week : int32_t, day : int32_t)
+
     Notes
     -----
     Assumes the inputs describe a valid date.
     """
     cdef:
         int32_t doy, dow
-        int woy
+        int32_t iso_year, iso_week
 
     doy = get_day_of_year(year, month, day)
     dow = dayofweek(year, month, day)
 
     # estimate
-    woy = (doy - 1) - dow + 3
-    if woy >= 0:
-        woy = woy // 7 + 1
+    iso_week = (doy - 1) - dow + 3
+    if iso_week >= 0:
+        iso_week = iso_week // 7 + 1
 
     # verify
-    if woy < 0:
-        if (woy > -2) or (woy == -2 and is_leapyear(year - 1)):
-            woy = 53
+    if iso_week < 0:
+        if (iso_week > -2) or (iso_week == -2 and is_leapyear(year - 1)):
+            iso_week = 53
         else:
-            woy = 52
-    elif woy == 53:
+            iso_week = 52
+    elif iso_week == 53:
         if 31 - day + dow < 3:
-            woy = 1
+            iso_week = 1
+
+    iso_year = year
+    if iso_week == 1 and doy > 7:
+        iso_year += 1
+
+    elif iso_week >= 52 and doy < 7:
+        iso_year -= 1
 
-    return woy
+    return iso_year, iso_week, dow + 1
 
 
 @cython.wraparound(False)

pandas/tests/tslibs/test_ccalendar.py

@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import date, datetime
 
 import numpy as np
 import pytest
@@ -25,3 +25,27 @@ def test_get_day_of_year_dt():
 
     expected = (dt - dt.replace(month=1, day=1)).days + 1
     assert result == expected
+
+
+@pytest.mark.parametrize(
+    "input_date_tuple, expected_iso_tuple",
+    [
+        [(2020, 1, 1), (2020, 1, 3)],
+        [(2019, 12, 31), (2020, 1, 2)],
+        [(2019, 12, 30), (2020, 1, 1)],
+        [(2009, 12, 31), (2009, 53, 4)],
+        [(2010, 1, 1), (2009, 53, 5)],
+        [(2010, 1, 3), (2009, 53, 7)],
+        [(2010, 1, 4), (2010, 1, 1)],
+        [(2006, 1, 1), (2005, 52, 7)],
+        [(2005, 12, 31), (2005, 52, 6)],
+        [(2008, 12, 28), (2008, 52, 7)],
+        [(2008, 12, 29), (2009, 1, 1)],
+    ],
+)
+def test_dt_correct_iso_8601_year_week_and_day(input_date_tuple, expected_iso_tuple):
+    assert (
+        ccalendar.get_iso_calendar(*input_date_tuple)
+        == date(*input_date_tuple).isocalendar()
+    )
+    assert ccalendar.get_iso_calendar(*input_date_tuple) == expected_iso_tuple