gh-158252: Share calendar helpers and clarify strptime fallback

Reuse the datetime calendar arithmetic for struct_time construction. Document the numeric parser scope and why even known-invalid inputs use the Python parser for error messages and error precedence.

Author: pganssle

Include/internal/pycore_time.h

@@ -317,6 +317,29 @@ extern PyTime_t _PyTimeFraction_Mul(
 extern double _PyTimeFraction_Resolution(
     const _PyTimeFraction *frac);
 
+/* year -> number of days before January 1st of year.  Remember that we
+ * start with year 1, so days_before_year(1) == 0.
+ */
+static inline int
+_PyTime_DaysBeforeYear(int year)
+{
+    int y = year - 1;
+    /* This is incorrect if year <= 0; we really want the floor
+     * here.  But so long as MINYEAR is 1, the smallest year this
+     * can see is 1.
+     */
+    assert(year >= 1);
+    return y*365 + y/4 - y/100 + y/400;
+}
+
+// Weekday from a valid Gregorian year and 1-based day of year; Monday is 0.
+static inline int
+_PyTime_Weekday(int year, int yday)
+{
+    return (_PyTime_DaysBeforeYear(year) + yday + 6) % 7;
+}
+
+
 // Locale-independent numeric strptime parsing.
 // A complete match returns 1; otherwise use Lib/_strptime.py. This function
 // neither allocates nor sets exceptions. The calendar date is validated, but

Modules/_datetimemodule.c

@@ -463,27 +463,13 @@ days_before_month(int year, int month)
     return days;
 }
 
-/* year -> number of days before January 1st of year.  Remember that we
- * start with year 1, so days_before_year(1) == 0.
- */
-static int
-days_before_year(int year)
-{
-    int y = year - 1;
-    /* This is incorrect if year <= 0; we really want the floor
-     * here.  But so long as MINYEAR is 1, the smallest year this
-     * can see is 1.
-     */
-    assert (year >= 1);
-    return y*365 + y/4 - y/100 + y/400;
-}
 
 /* Number of days in 4, 100, and 400 year cycles.  That these have
  * the correct values is asserted in the module init function.
  */
-#define DI4Y    1461    /* days_before_year(5); days in 4 years */
-#define DI100Y  36524   /* days_before_year(101); days in 100 years */
-#define DI400Y  146097  /* days_before_year(401); days in 400 years  */
+#define DI4Y    1461    /* _PyTime_DaysBeforeYear(5); days in 4 years */
+#define DI100Y  36524   /* _PyTime_DaysBeforeYear(101); days in 100 years */
+#define DI400Y  146097  /* _PyTime_DaysBeforeYear(401); days in 400 years  */
 
 /* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. */
 static void
@@ -573,14 +559,14 @@ ord_to_ymd(int ordinal, int *year, int *month, int *day)
 static int
 ymd_to_ord(int year, int month, int day)
 {
-    return days_before_year(year) + days_before_month(year, month) + day;
+    return _PyTime_DaysBeforeYear(year) + days_before_month(year, month) + day;
 }
 
 /* Day of week, where Monday==0, ..., Sunday==6.  1/1/1 was a Monday. */
 static int
 weekday(int year, int month, int day)
 {
-    return (ymd_to_ord(year, month, day) + 6) % 7;
+    return _PyTime_Weekday(year, days_before_month(year, month) + day);
 }
 
 /* Ordinal of the Monday starting week 1 of the ISO year.  Week 1 is the
@@ -7722,19 +7708,19 @@ _datetime_exec(PyObject *module)
      * pasting together 4 single years.
      */
     static_assert(DI4Y == 4 * 365 + 1, "DI4Y");
-    assert(DI4Y == days_before_year(4+1));
+    assert(DI4Y == _PyTime_DaysBeforeYear(4+1));
 
     /* Similarly, a 400-year cycle has an extra leap day over what we'd
      * get from pasting together 4 100-year cycles.
      */
     static_assert(DI400Y == 4 * DI100Y + 1, "DI400Y");
-    assert(DI400Y == days_before_year(400+1));
+    assert(DI400Y == _PyTime_DaysBeforeYear(400+1));
 
     /* OTOH, a 100-year cycle has one fewer leap day than we'd get from
      * pasting together 25 4-year cycles.
      */
     static_assert(DI100Y == 25 * DI4Y - 1, "DI100Y");
-    assert(DI100Y == days_before_year(100+1));
+    assert(DI100Y == _PyTime_DaysBeforeYear(100+1));
 
     if (set_current_module(interp, module) < 0) {
         goto error;

Modules/timemodule.c

@@ -998,14 +998,10 @@ time_strptime(PyObject *self, PyObject *args)
         if (result == NULL) {
             return NULL;
         }
-        /* January 1 of year 1 was a Monday. */
-        int year = fields.year - 1;
-        int weekday = (365 * year + year / 4 - year / 100 + year / 400 +
-                       fields.yday - 1) % 7;
         const int values[] = {
             fields.year, fields.month, fields.day,
             fields.hour, fields.minute, fields.second,
-            weekday, fields.yday, -1
+            _PyTime_Weekday(fields.year, fields.yday), fields.yday, -1
         };
         for (size_t i = 0; i < Py_ARRAY_LENGTH(values); i++) {
             PyObject *value = PyLong_FromLong(values[i]);

Python/pytime.c

@@ -1418,15 +1418,18 @@ _PyDeadline_Get(PyTime_t deadline)
 }
 
 
-/* Locale-independent numeric strptime parsing.
+/* Implement common parts of strptime in C to improve performance. Callers
+ * fall back to Lib/_strptime.py for a full parse when this doesn't match.
  *
- * Return 1 for a complete numeric match, or 0 to use Lib/_strptime.py.
- * Parsing doesn't allocate or set exceptions. In particular, mismatches may
- * require regex backtracking, so their diagnostics belong to the fallback.
+ * Supported inputs are exact str objects containing only ASCII, with:
+ * - numeric %Y, %y, %m, %d, %H, %M, %S, and %f fields;
+ * - a terminal %z: empty, Z, or +/-HHMM or +/-HH:MM with hours below 24;
+ * - literal characters, %%, and ASCII whitespace.
+ * Duplicate directives, mixed %Y/%y, and day-of-month without a year use the
+ * fallback. So do other directives (including locale-dependent names and
+ * week/day-of-year calculations), and offsets with seconds or fractions.
  */
 
-
-
 static int
 strptime_digits(const unsigned char *data, Py_ssize_t length, Py_ssize_t pos,
                 int minimum, int maximum, int *value)
@@ -1481,6 +1484,15 @@ strptime_offset(const unsigned char *data, Py_ssize_t length, Py_ssize_t pos,
     return 1;
 }
 
+/* Return 1 for a complete numeric match, or 0 if fallback is required.
+ *
+ * Parsing doesn't allocate or set exceptions. Some mismatches require regex
+ * backtracking, but even inputs known to be invalid use the Python parser:
+ * it owns the exception messages and error precedence. For example, month 13
+ * and empty input can't be repaired by backtracking, but diagnosing them here
+ * would duplicate the Python parser's error handling. A return value of 0
+ * therefore doesn't distinguish invalid input from an unsupported format.
+ */
 int
 _PyTime_Strptime(PyObject *string, PyObject *format, _PyTime_StrptimeFields *fields)
 {