From e2feb054f7ff06537396356d13ba2547312c73c9 Mon Sep 17 00:00:00 2001 From: Aleksandr Mazalov Date: Tue, 10 Nov 2026 07:28:21 -0600 Subject: [PATCH 1/8] gh-161746: Use the Neri-Schneider algorithm for ordinal to date conversion Replace the 400/100/4/1-year cycle decomposition and the month estimate-and-correct step in ord_to_ymd() (Modules/_datetimemodule.c) and _ord2ymd() (Lib/_pydatetime.py) with Figure 12 of Neri and Schneider, "Euclidean affine functions and their application to calendar algorithms" (Softw Pract Exper. 2023;53(4):937-970), which GCC's libstdc++, the Linux kernel, .NET and Go already use. The C version computes the year and the month steps with one multiplication each, and does the century step in 64 bits so that every positive int ordinal gives the same result as before. The pure-Python version uses plain floor division. Both versions return the same results as the old code for every ordinal from 1 to 3,652,059; the C version also for every positive int, and the pure-Python one for 2.3 million other integers, including negative and huge ones. In microbenchmarks on x86-64 (gcc 13, -O3), date.fromordinal() on random dates is about 1.4x faster, date + timedelta across a month boundary and date.fromisocalendar() about 1.2x faster, and the pure-Python date.fromordinal() about 1.3x faster. Add a test for the first and last days of every month in years at the start and the end of the 4-, 100- and 400-year cycles. Co-Authored-By: Claude Fable 5.2 --- Lib/_pydatetime.py | 79 +++-------- Lib/test/datetimetester.py | 17 +++ ...-11-10-13-28-10.gh-issue-161746.HxgY9R.rst | 4 + Modules/_datetimemodule.c | 126 +++++++----------- 4 files changed, 89 insertions(+), 137 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst diff --git a/Lib/_pydatetime.py b/Lib/_pydatetime.py index 5a8fec43e668a53..7c747743822726d 100644 --- a/Lib/_pydatetime.py +++ b/Lib/_pydatetime.py @@ -90,67 +90,28 @@ def _ymd2ord(year, month, day): # pasting together 25 4-year cycles. assert _DI100Y == 25 * _DI4Y - 1 -def _ord2ymd(n): +def _ord2ymd(ordinal): "ordinal -> (year, month, day), considering 01-Jan-0001 as day 1." - # n is a 1-based index, starting at 1-Jan-1. The pattern of leap years - # repeats exactly every 400 years. The basic strategy is to find the - # closest 400-year boundary at or before n, then work with the offset - # from that boundary to n. Life is much clearer if we subtract 1 from - # n first -- then the values of n at 400-year boundaries are exactly - # those divisible by _DI400Y: - # - # D M Y n n-1 - # -- --- ---- ---------- ---------------- - # 31 Dec -400 -_DI400Y -_DI400Y -1 - # 1 Jan -399 -_DI400Y +1 -_DI400Y 400-year boundary - # ... - # 30 Dec 000 -1 -2 - # 31 Dec 000 0 -1 - # 1 Jan 001 1 0 400-year boundary - # 2 Jan 001 2 1 - # 3 Jan 001 3 2 - # ... - # 31 Dec 400 _DI400Y _DI400Y -1 - # 1 Jan 401 _DI400Y +1 _DI400Y 400-year boundary - n -= 1 - n400, n = divmod(n, _DI400Y) - year = n400 * 400 + 1 # ..., -399, 1, 401, ... - - # Now n is the (non-negative) offset, in days, from January 1 of year, to - # the desired date. Now compute how many 100-year cycles precede n. - # Note that it's possible for n100 to equal 4! In that case 4 full - # 100-year cycles precede the desired day, which implies the desired - # day is December 31 at the end of a 400-year cycle. - n100, n = divmod(n, _DI100Y) - - # Now compute how many 4-year cycles precede it. - n4, n = divmod(n, _DI4Y) - - # And now how many single years. Again n1 can be 4, and again meaning - # that the desired day is December 31 at the end of the 4-year cycle. - n1, n = divmod(n, 365) - - year += n100 * 100 + n4 * 4 + n1 - if n1 == 4 or n100 == 4: - assert n == 0 - return year-1, 12, 31 - - # Now the year is correct, and n is the offset from January 1. We find - # the month via an estimate that's either exact or one too large. - leapyear = n1 == 3 and (n4 != 24 or n100 == 3) - assert leapyear == _is_leap(year) - month = (n + 50) >> 5 - preceding = _DAYS_BEFORE_MONTH[month] + (month > 2 and leapyear) - if preceding > n: # estimate is too large - month -= 1 - preceding -= _DAYS_IN_MONTH[month] + (month == 2 and leapyear) - n -= preceding - assert 0 <= n < _days_in_month(year, month) - - # Now the year and month are correct, and n is the offset from the - # start of that month: we're done! - return year, month, n+1 + # This is Figure 12 of Neri and Schneider, "Euclidean affine functions + # and their application to calendar algorithms", Softw Pract Exper. + # 2023;53(4):937-970. It works in a computational calendar whose years + # start on March 1, so that the irregular February comes last, and + # computes each step (century, year, month, day) as a Euclidean affine + # function (a*n + b) // d. Floor division keeps it exact for every int. + days = ordinal + 305 # day 0 is 0000-03-01 + century, rest = divmod(4 * days + 3, _DI400Y) + day_of_century = rest // 4 + year_of_century, rest = divmod(4 * day_of_century + 3, _DI4Y) + day_of_year = rest // 4 # day 0 is March 1 + # Month lengths repeat every 5 months (153 days) from March on; + # month 3 is March, ..., month 14 is February. + month, rest = divmod(5 * day_of_year + 461, 153) + day = rest // 5 + 1 + year = 100 * century + year_of_century + if month > 12: # January or February + return year + 1, month - 12, day + return year, month, day # Month and day names. For localized versions, see the calendar module. _MONTHNAMES = [None, "Jan", "Feb", "Mar", "Apr", "May", "Jun", diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py index 00a9d2bca3f4779..c2a6aea5c41bc97 100644 --- a/Lib/test/datetimetester.py +++ b/Lib/test/datetimetester.py @@ -1434,6 +1434,23 @@ def test_ordinal_conversions(self): self.assertEqual(d, self.theclass.fromordinal(n)) n += 1 + # Check the first and last days of every month in years at the + # start and the end of the 4-, 100- and 400-year cycles. + for year in (1, 3, 4, 5, 99, 100, 101, 399, 400, 401, 1899, 1900, + 1901, 1999, 2001, 2100, 2399, 2400, 9996, 9999): + isleap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0) + n = self.theclass(year, 1, 1).toordinal() + for month, maxday in zip(range(1, 13), dim): + if month == 2 and isleap: + maxday += 1 + for day, ordinal in (1, n), (maxday, n + maxday - 1): + with self.subTest(year=year, month=month, day=day): + d = self.theclass(year, month, day) + self.assertEqual(d.toordinal(), ordinal) + self.assertEqual(d, self.theclass.fromordinal(ordinal)) + n += maxday + self.assertEqual(n, self.theclass(year, 12, 31).toordinal() + 1) + def test_extreme_ordinals(self): a = self.theclass.min a = self.theclass(a.year, a.month, a.day) # get rid of time parts diff --git a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst new file mode 100644 index 000000000000000..ce40a825abc03b1 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst @@ -0,0 +1,4 @@ +Speed up conversion of ordinals to dates in :mod:`datetime`, used by +:meth:`~datetime.date.fromordinal`, :meth:`~datetime.date.fromisocalendar` +and :class:`~datetime.timedelta` arithmetic, by switching to the +Neri–Schneider algorithm. diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index b9939d5cc71a319..4ebafcc75cd0cd9 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -471,88 +471,58 @@ days_before_month(int year, int month) #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. */ +/* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. + * + * This is Figure 12 of Neri and Schneider [1], the algorithm also used by + * the Linux kernel's rtc_time64_to_tm() and by libstdc++'s . It + * works in a computational calendar whose years start on March 1, so that + * the irregular February comes last, and evaluates every step (century, + * year, month, day) as a Euclidean affine function (a*n + b) / d, with no + * lookup tables and no estimate-and-correct step. The year and the month + * steps each take one multiplication whose high bits are the quotient and + * whose low bits give the remainder. The century step is done in 64 bits + * so that every positive int ordinal gives the same result as the classic + * algorithm. + * + * [1] Neri C, Schneider L. Euclidean affine functions and their application + * to calendar algorithms. Softw Pract Exper. 2023;53(4):937-970. + * doi:10.1002/spe.3172 + */ static void ord_to_ymd(int ordinal, int *year, int *month, int *day) { - int n, n1, n4, n100, n400, leapyear, preceding; - - /* ordinal is a 1-based index, starting at 1-Jan-1. The pattern of - * leap years repeats exactly every 400 years. The basic strategy is - * to find the closest 400-year boundary at or before ordinal, then - * work with the offset from that boundary to ordinal. Life is much - * clearer if we subtract 1 from ordinal first -- then the values - * of ordinal at 400-year boundaries are exactly those divisible - * by DI400Y: - * - * D M Y n n-1 - * -- --- ---- ---------- ---------------- - * 31 Dec -400 -DI400Y -DI400Y -1 - * 1 Jan -399 -DI400Y +1 -DI400Y 400-year boundary - * ... - * 30 Dec 000 -1 -2 - * 31 Dec 000 0 -1 - * 1 Jan 001 1 0 400-year boundary - * 2 Jan 001 2 1 - * 3 Jan 001 3 2 - * ... - * 31 Dec 400 DI400Y DI400Y -1 - * 1 Jan 401 DI400Y +1 DI400Y 400-year boundary - */ assert(ordinal >= 1); - --ordinal; - n400 = ordinal / DI400Y; - n = ordinal % DI400Y; - *year = n400 * 400 + 1; - - /* Now n is the (non-negative) offset, in days, from January 1 of - * year, to the desired date. Now compute how many 100-year cycles - * precede n. - * Note that it's possible for n100 to equal 4! In that case 4 full - * 100-year cycles precede the desired day, which implies the - * desired day is December 31 at the end of a 400-year cycle. - */ - n100 = n / DI100Y; - n = n % DI100Y; - - /* Now compute how many 4-year cycles precede it. */ - n4 = n / DI4Y; - n = n % DI4Y; - - /* And now how many single years. Again n1 can be 4, and again - * meaning that the desired day is December 31 at the end of the - * 4-year cycle. - */ - n1 = n / 365; - n = n % 365; - - *year += n100 * 100 + n4 * 4 + n1; - if (n1 == 4 || n100 == 4) { - assert(n == 0); - *year -= 1; - *month = 12; - *day = 31; - return; - } - - /* Now the year is correct, and n is the offset from January 1. We - * find the month via an estimate that's either exact or one too - * large. - */ - leapyear = n1 == 3 && (n4 != 24 || n100 == 3); - assert(leapyear == is_leap(*year)); - *month = (n + 50) >> 5; - preceding = (_days_before_month[*month] + (*month > 2 && leapyear)); - if (preceding > n) { - /* estimate is too large */ - *month -= 1; - preceding -= days_in_month(*year, *month); - } - n -= preceding; - assert(0 <= n); - assert(n < days_in_month(*year, *month)); - - *day = n + 1; + /* Days since 0000-03-01, the start of the computational calendar. */ + const uint64_t days = (uint64_t)ordinal + 305; + + /* century = (4*days + 3) / DI400Y, and the day of the century. */ + const uint64_t century_scaled = 4 * days + 3; + const uint32_t century = (uint32_t)(century_scaled / DI400Y); + const uint32_t day_of_century = (uint32_t)(century_scaled % DI400Y) / 4; + + /* year_of_century = (4*day_of_century + 3) / DI4Y, and the day of the + * year (March 1 is day 0), from one product: 2939745 is + * ceil(2**32 / DI4Y), so the high 32 bits are the quotient and the low + * 32 bits encode the remainder. */ + const uint32_t year_scaled = 4 * day_of_century + 3; + const uint64_t year_product = (uint64_t)2939745 * year_scaled; + const uint32_t year_of_century = (uint32_t)(year_product >> 32); + const uint32_t day_of_year = (uint32_t)year_product / 2939745 / 4; + + /* month = (5*day_of_year + 461) / 153 (March = 3, ..., February = 14), + * and the day of the month, from one product: 2141 is about + * 2**16 * 5 / 153 and 197913 the matching offset, so the high 16 bits + * are the month and the low 16 bits encode the day. */ + const uint32_t month_product = 2141 * day_of_year + 197913; + const uint32_t march_based_month = month_product >> 16; + const uint32_t day_of_month = (month_product & 0xFFFF) / 2141; + + /* January and February belong to the next calendar year. */ + const uint32_t is_jan_or_feb = day_of_year >= 306; + + *year = (int)(100 * century + year_of_century + is_jan_or_feb); + *month = (int)(is_jan_or_feb ? march_based_month - 12 : march_based_month); + *day = (int)(day_of_month + 1); } /* year, month, day -> ordinal, considering 01-Jan-0001 as day 1. */ From 7144141777757701e5fab378187cf28bd9fa1e09 Mon Sep 17 00:00:00 2001 From: Aleksandr Mazalov Date: Tue, 10 Nov 2026 15:22:13 -0600 Subject: [PATCH 2/8] Simplify ord_to_ymd() to mirror _ord2ymd(); expand NEWS Use plain division and modulo by constants instead of hand-derived multiply-shift constants; compilers emit multiplications anyway. Add a link to the paper and rough speedups to the NEWS entry. Co-Authored-By: Claude Opus 5.5 --- ...-11-10-13-28-10.gh-issue-161746.HxgY9R.rst | 9 +-- Modules/_datetimemodule.c | 68 ++++++++----------- 2 files changed, 32 insertions(+), 45 deletions(-) diff --git a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst index ce40a825abc03b1..64cac2100ff094e 100644 --- a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst +++ b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst @@ -1,4 +1,5 @@ -Speed up conversion of ordinals to dates in :mod:`datetime`, used by -:meth:`~datetime.date.fromordinal`, :meth:`~datetime.date.fromisocalendar` -and :class:`~datetime.timedelta` arithmetic, by switching to the -Neri–Schneider algorithm. +Speed up conversion of ordinals to dates in :mod:`datetime` by switching to +the `Neri–Schneider algorithm `__. +:meth:`~datetime.date.fromordinal` is about 30% faster, and +:meth:`~datetime.date.fromisocalendar` and :class:`~datetime.timedelta` +arithmetic across month boundaries are about 10–20% faster. diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index 4ebafcc75cd0cd9..a86fc8fd8f781b4 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -473,16 +473,14 @@ days_before_month(int year, int month) /* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. * - * This is Figure 12 of Neri and Schneider [1], the algorithm also used by - * the Linux kernel's rtc_time64_to_tm() and by libstdc++'s . It - * works in a computational calendar whose years start on March 1, so that - * the irregular February comes last, and evaluates every step (century, - * year, month, day) as a Euclidean affine function (a*n + b) / d, with no - * lookup tables and no estimate-and-correct step. The year and the month - * steps each take one multiplication whose high bits are the quotient and - * whose low bits give the remainder. The century step is done in 64 bits - * so that every positive int ordinal gives the same result as the classic - * algorithm. + * This is Figure 12 of Neri and Schneider [1], and the same steps as + * _ord2ymd() in Lib/_pydatetime.py. It works in a computational calendar + * whose years start on March 1, so that the irregular February comes last, + * and computes each step (century, year, month, day) as a Euclidean affine + * function (a*n + b) / d, with no lookup tables and no estimate-and-correct + * step. The divisors are constants, so compilers emit multiplications, not + * divisions. The century step is done in 64 bits so that every positive + * int ordinal gives the same result as the classic algorithm. * * [1] Neri C, Schneider L. Euclidean affine functions and their application * to calendar algorithms. Softw Pract Exper. 2023;53(4):937-970. @@ -492,37 +490,25 @@ static void ord_to_ymd(int ordinal, int *year, int *month, int *day) { assert(ordinal >= 1); - /* Days since 0000-03-01, the start of the computational calendar. */ - const uint64_t days = (uint64_t)ordinal + 305; - - /* century = (4*days + 3) / DI400Y, and the day of the century. */ - const uint64_t century_scaled = 4 * days + 3; - const uint32_t century = (uint32_t)(century_scaled / DI400Y); - const uint32_t day_of_century = (uint32_t)(century_scaled % DI400Y) / 4; - - /* year_of_century = (4*day_of_century + 3) / DI4Y, and the day of the - * year (March 1 is day 0), from one product: 2939745 is - * ceil(2**32 / DI4Y), so the high 32 bits are the quotient and the low - * 32 bits encode the remainder. */ - const uint32_t year_scaled = 4 * day_of_century + 3; - const uint64_t year_product = (uint64_t)2939745 * year_scaled; - const uint32_t year_of_century = (uint32_t)(year_product >> 32); - const uint32_t day_of_year = (uint32_t)year_product / 2939745 / 4; - - /* month = (5*day_of_year + 461) / 153 (March = 3, ..., February = 14), - * and the day of the month, from one product: 2141 is about - * 2**16 * 5 / 153 and 197913 the matching offset, so the high 16 bits - * are the month and the low 16 bits encode the day. */ - const uint32_t month_product = 2141 * day_of_year + 197913; - const uint32_t march_based_month = month_product >> 16; - const uint32_t day_of_month = (month_product & 0xFFFF) / 2141; - - /* January and February belong to the next calendar year. */ - const uint32_t is_jan_or_feb = day_of_year >= 306; - - *year = (int)(100 * century + year_of_century + is_jan_or_feb); - *month = (int)(is_jan_or_feb ? march_based_month - 12 : march_based_month); - *day = (int)(day_of_month + 1); + const uint64_t days = (uint64_t)ordinal + 305; /* day 0 is 0000-03-01 */ + const uint32_t century = (uint32_t)((4 * days + 3) / DI400Y); + const uint32_t day_of_century = (uint32_t)((4 * days + 3) % DI400Y) / 4; + const uint32_t year_of_century = (4 * day_of_century + 3) / DI4Y; + const uint32_t day_of_year = (4 * day_of_century + 3) % DI4Y / 4; + /* Month lengths repeat every 5 months (153 days) from March on; + * month 3 is March, ..., month 14 is February. */ + const uint32_t m = (5 * day_of_year + 461) / 153; + const uint32_t d = (5 * day_of_year + 461) % 153 / 5 + 1; + const uint32_t y = 100 * century + year_of_century; + if (m > 12) { /* January or February */ + *year = (int)(y + 1); + *month = (int)(m - 12); + } + else { + *year = (int)y; + *month = (int)m; + } + *day = (int)d; } /* year, month, day -> ordinal, considering 01-Jan-0001 as day 1. */ From b3f74a0ae1bcdde28b179d5245ba1642b90e1386 Mon Sep 17 00:00:00 2001 From: Aleksandr Mazalov Date: Tue, 10 Nov 2026 22:01:35 -0600 Subject: [PATCH 3/8] Address review: 32-bit ord_to_ymd(), property test, comments * ord_to_ymd() uses only uint32_t; fromordinal() shifts larger ordinals by 400-year cycles, so the error message is unchanged. * Replace the hand-picked loop with a Hypothesis round-trip test and add tests for the error year after MAXORDINAL. * Explain each step in the comments of both implementations; cite the paper by DOI. * Update the NEWS entry with new measurements. Co-Authored-By: Claude Opus 5.5 --- Lib/_pydatetime.py | 42 +++++++++---- Lib/test/datetimetester.py | 42 ++++++++----- ...-11-10-13-28-10.gh-issue-161746.HxgY9R.rst | 8 ++- Modules/_datetimemodule.c | 63 ++++++++++++++----- 4 files changed, 109 insertions(+), 46 deletions(-) diff --git a/Lib/_pydatetime.py b/Lib/_pydatetime.py index 7c747743822726d..d96a6e63b0717cf 100644 --- a/Lib/_pydatetime.py +++ b/Lib/_pydatetime.py @@ -93,23 +93,43 @@ def _ymd2ord(year, month, day): def _ord2ymd(ordinal): "ordinal -> (year, month, day), considering 01-Jan-0001 as day 1." - # This is Figure 12 of Neri and Schneider, "Euclidean affine functions - # and their application to calendar algorithms", Softw Pract Exper. - # 2023;53(4):937-970. It works in a computational calendar whose years - # start on March 1, so that the irregular February comes last, and - # computes each step (century, year, month, day) as a Euclidean affine - # function (a*n + b) // d. Floor division keeps it exact for every int. - days = ordinal + 305 # day 0 is 0000-03-01 + # This follows Neri and Schneider, "Euclidean affine functions and their + # application to calendar algorithms", Softw Pract Exper. + # 2023;53(4):937-970, https://doi.org/10.1002/spe.3172. + # ord_to_ymd() in Modules/_datetimemodule.c does the same steps. + # + # February is the irregular month, so count in a calendar whose years + # start on March 1. Then the leap day, when there is one, is the last + # day of its year, and the long year of each 4-year cycle and the long + # century of each 400-year cycle come last as well. 0001-01-01 is 306 + # days after 0000-03-01. + days = ordinal + 305 + + # A century is _DI400Y/4 = 36524.25 days on average, so century c starts + # on day floor(_DI400Y*c/4): the first three centuries of a 400-year + # cycle have 36524 days and the last one 36525. Inverting that, day n + # is in century (4*n + 3) // _DI400Y, and the remainder // 4 is its day + # within the century. century, rest = divmod(4 * days + 3, _DI400Y) day_of_century = rest // 4 + + # Within a century, years follow the same pattern with _DI4Y/4 = 365.25 + # days (three common years, then a leap year; a 36524-day century just + # ends one day early). year_of_century, rest = divmod(4 * day_of_century + 3, _DI4Y) - day_of_year = rest // 4 # day 0 is March 1 - # Month lengths repeat every 5 months (153 days) from March on; - # month 3 is March, ..., month 14 is February. + day_of_year = rest // 4 # March 1 is day 0 + + # From March on, month lengths follow 31, 30, 31, 30, 31: a 153-day + # block that repeats for March-July, August-December, and then + # January-February, cut short by the end of the year. So + # (5*day_of_year + 2) // 153 is the number of whole months before the + # day, and the remainder // 5 is the day within its month. Adding + # 3*153 = 459 makes March month 3; months 13 and 14 are January and + # February of the next calendar year. month, rest = divmod(5 * day_of_year + 461, 153) day = rest // 5 + 1 year = 100 * century + year_of_century - if month > 12: # January or February + if month > 12: return year + 1, month - 12, day return year, month, day diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py index c2a6aea5c41bc97..b6c6f4a8bad95e8 100644 --- a/Lib/test/datetimetester.py +++ b/Lib/test/datetimetester.py @@ -23,6 +23,7 @@ from test import support from test.support import is_resource_enabled, ALWAYS_EQ, LARGEST, SMALLEST from test.support import os_helper, script_helper +from test.support.hypothesis_helper import hypothesis import datetime as datetime_module from datetime import MINYEAR, MAXYEAR @@ -1434,22 +1435,24 @@ def test_ordinal_conversions(self): self.assertEqual(d, self.theclass.fromordinal(n)) n += 1 - # Check the first and last days of every month in years at the - # start and the end of the 4-, 100- and 400-year cycles. - for year in (1, 3, 4, 5, 99, 100, 101, 399, 400, 401, 1899, 1900, - 1901, 1999, 2001, 2100, 2399, 2400, 9996, 9999): - isleap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0) - n = self.theclass(year, 1, 1).toordinal() - for month, maxday in zip(range(1, 13), dim): - if month == 2 and isleap: - maxday += 1 - for day, ordinal in (1, n), (maxday, n + maxday - 1): - with self.subTest(year=year, month=month, day=day): - d = self.theclass(year, month, day) - self.assertEqual(d.toordinal(), ordinal) - self.assertEqual(d, self.theclass.fromordinal(ordinal)) - n += maxday - self.assertEqual(n, self.theclass(year, 12, 31).toordinal() + 1) + # The ends of the 4-, 100- and 400-year cycles are the tricky cases. + @hypothesis.given(hypothesis.strategies.dates()) + @hypothesis.example(date(1, 1, 1)) + @hypothesis.example(date(4, 2, 29)) + @hypothesis.example(date(4, 12, 31)) + @hypothesis.example(date(100, 2, 28)) + @hypothesis.example(date(100, 3, 1)) + @hypothesis.example(date(100, 12, 31)) + @hypothesis.example(date(400, 2, 29)) + @hypothesis.example(date(400, 12, 31)) + @hypothesis.example(date(401, 1, 1)) + @hypothesis.example(date(2000, 3, 1)) + @hypothesis.example(date(9999, 12, 31)) + def test_ordinal_roundtrip(self, d): + # Rebuild d with the class under test: the strategy and the examples + # may come from the other implementation. + d = self.theclass(d.year, d.month, d.day) + self.assertEqual(self.theclass.fromordinal(d.toordinal()), d) def test_extreme_ordinals(self): a = self.theclass.min @@ -1472,6 +1475,13 @@ def test_extreme_ordinals(self): self.assertRaises(ValueError, lambda: a.fromordinal(aord + 1)) + # Past the maximum, the error still reports the year of the ordinal. + for n, year in ((aord + 1, 10000), (aord + 146097 + 1, 10400), + (2**31 - 1, 5879611)): + with self.subTest(n=n): + with self.assertRaisesRegex(ValueError, rf"\b{year}\b"): + self.theclass.fromordinal(n) + b = a - timedelta(days=1) self.assertEqual(b.toordinal(), aord - 1) self.assertEqual(b, self.theclass.fromordinal(aord - 1)) diff --git a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst index 64cac2100ff094e..d7bf40d6e73267e 100644 --- a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst +++ b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst @@ -1,5 +1,7 @@ Speed up conversion of ordinals to dates in :mod:`datetime` by switching to -the `Neri–Schneider algorithm `__. -:meth:`~datetime.date.fromordinal` is about 30% faster, and +the `Neri–Schneider algorithm `__. +:meth:`~datetime.date.fromordinal` is about 15% faster in the C +implementation and about 30% faster in the pure-Python implementation. +Other operations that convert ordinals to dates, such as :meth:`~datetime.date.fromisocalendar` and :class:`~datetime.timedelta` -arithmetic across month boundaries are about 10–20% faster. +arithmetic, also benefit. diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index a86fc8fd8f781b4..e4845c538dfb9db 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -473,30 +473,49 @@ days_before_month(int year, int month) /* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. * - * This is Figure 12 of Neri and Schneider [1], and the same steps as - * _ord2ymd() in Lib/_pydatetime.py. It works in a computational calendar - * whose years start on March 1, so that the irregular February comes last, - * and computes each step (century, year, month, day) as a Euclidean affine - * function (a*n + b) / d, with no lookup tables and no estimate-and-correct - * step. The divisors are constants, so compilers emit multiplications, not - * divisions. The century step is done in 64 bits so that every positive - * int ordinal gives the same result as the classic algorithm. + * This follows Neri and Schneider [1]; _ord2ymd() in Lib/_pydatetime.py + * does the same steps. + * + * February is the irregular month, so we count in a calendar whose years + * start on March 1. Then the leap day, when there is one, is the last day + * of its year, and the long year of each 4-year cycle and the long century + * of each 400-year cycle come last as well. + * + * A century is DI400Y/4 = 36524.25 days on average, so century c starts on + * day floor(DI400Y*c/4); the first three centuries of a 400-year cycle have + * 36524 days and the last one 36525. Inverting that, day n is in century + * (4*n + 3) / DI400Y, and (4*n + 3) % DI400Y / 4 is its day within the + * century. Within a century, years follow the same pattern with + * DI4Y/4 = 365.25 days (three common years, then a leap year; a 36524-day + * century just ends one day early), so the same step with DI4Y gives the + * year and the day within it. + * + * From March on, month lengths follow 31, 30, 31, 30, 31, a 153-day block + * that repeats: March-July, August-December, then January-February (cut + * short by the end of the year). So for day n of the year (March 1 is + * day 0), (5*n + 2) / 153 is the number of whole months before it and + * (5*n + 2) % 153 / 5 is the day within its month. We add 3*153 = 459 so + * that March is month 3; months 13 and 14 are January and February of the + * next calendar year. + * + * All intermediate values fit in 32 bits as long as ordinal is at most + * MAXORDINAL + 2 (iso_to_ymd() can reach 10000-01-02). + * date.fromordinal() handles larger ordinals itself. * * [1] Neri C, Schneider L. Euclidean affine functions and their application * to calendar algorithms. Softw Pract Exper. 2023;53(4):937-970. - * doi:10.1002/spe.3172 + * https://doi.org/10.1002/spe.3172 */ static void ord_to_ymd(int ordinal, int *year, int *month, int *day) { - assert(ordinal >= 1); - const uint64_t days = (uint64_t)ordinal + 305; /* day 0 is 0000-03-01 */ - const uint32_t century = (uint32_t)((4 * days + 3) / DI400Y); - const uint32_t day_of_century = (uint32_t)((4 * days + 3) % DI400Y) / 4; + assert(1 <= ordinal && ordinal <= MAXORDINAL + 2); + /* Days since 0000-03-01; 0001-01-01 is 306 days later. */ + const uint32_t days = (uint32_t)ordinal + 305; + const uint32_t century = (4 * days + 3) / DI400Y; + const uint32_t day_of_century = (4 * days + 3) % DI400Y / 4; const uint32_t year_of_century = (4 * day_of_century + 3) / DI4Y; const uint32_t day_of_year = (4 * day_of_century + 3) % DI4Y / 4; - /* Month lengths repeat every 5 months (153 days) from March on; - * month 3 is March, ..., month 14 is February. */ const uint32_t m = (5 * day_of_year + 461) / 153; const uint32_t d = (5 * day_of_year + 461) % 153 / 5 + 1; const uint32_t y = 100 * century + year_of_century; @@ -3395,7 +3414,19 @@ datetime_date_fromordinal_impl(PyTypeObject *type, int ordinal) PyErr_SetString(PyExc_ValueError, "ordinal must be >= 1"); return NULL; } - ord_to_ymd(ordinal, &year, &month, &day); + if (ordinal <= MAXORDINAL) { + ord_to_ymd(ordinal, &year, &month, &day); + } + else { + /* Out of range: find the year anyway, so new_date_subclass_ex() + * raises the usual "year must be in 1..9999, not N" error. The + * calendar repeats every 400 years (DI400Y days), so convert the + * equivalent date in the first 400-year cycle and add the years + * back. */ + int cycles = (ordinal - 1) / DI400Y; + ord_to_ymd(ordinal - cycles * DI400Y, &year, &month, &day); + year += 400 * cycles; + } return new_date_subclass_ex(year, month, day, type); } From 3688a1001fe78f4dca8a9d65d685102933cd7366 Mon Sep 17 00:00:00 2001 From: mazalovmx Date: Wed, 11 Nov 2026 11:20:23 -0600 Subject: [PATCH 4/8] Silence the typing.AnyStr DeprecationWarning when importing Hypothesis test.test___all__ imports test.datetimetester, which now imports Hypothesis. Hypothesis imports the deprecated typing.AnyStr, and test___all__ fails on the unexpected DeprecationWarning. Co-Authored-By: Claude Opus 5.5 --- Lib/test/support/hypothesis_helper.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/Lib/test/support/hypothesis_helper.py b/Lib/test/support/hypothesis_helper.py index 6249ba43f06716a..31852d267a287b6 100644 --- a/Lib/test/support/hypothesis_helper.py +++ b/Lib/test/support/hypothesis_helper.py @@ -1,7 +1,14 @@ import os +import warnings try: - import hypothesis + with warnings.catch_warnings(): + # Hypothesis imports typing.AnyStr, which is deprecated. Silence the + # warning so that test.test___all__ can import test modules that use + # Hypothesis. + warnings.filterwarnings("ignore", "'typing.AnyStr' is deprecated", + DeprecationWarning) + import hypothesis except ImportError: from . import _hypothesis_stubs as hypothesis else: From 8ea445bffa8f33ef5c2f084c9cf35e7c17c14ab7 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 14 Nov 2026 15:32:42 +0000 Subject: [PATCH 5/8] Tidy up the comments Reduce duplication and make them a little more succinct. --- Lib/_pydatetime.py | 34 ++++++++----------------------- Modules/_datetimemodule.c | 43 ++++++--------------------------------- 2 files changed, 15 insertions(+), 62 deletions(-) diff --git a/Lib/_pydatetime.py b/Lib/_pydatetime.py index d96a6e63b0717cf..b974887fbe09703 100644 --- a/Lib/_pydatetime.py +++ b/Lib/_pydatetime.py @@ -93,39 +93,23 @@ def _ymd2ord(year, month, day): def _ord2ymd(ordinal): "ordinal -> (year, month, day), considering 01-Jan-0001 as day 1." - # This follows Neri and Schneider, "Euclidean affine functions and their - # application to calendar algorithms", Softw Pract Exper. - # 2023;53(4):937-970, https://doi.org/10.1002/spe.3172. + # Neri and Schneider's algorithm, https://doi.org/10.1002/spe.3172. # ord_to_ymd() in Modules/_datetimemodule.c does the same steps. # - # February is the irregular month, so count in a calendar whose years - # start on March 1. Then the leap day, when there is one, is the last - # day of its year, and the long year of each 4-year cycle and the long - # century of each 400-year cycle come last as well. 0001-01-01 is 306 - # days after 0000-03-01. + # Count days from 0000-03-01, so that the leap day is the last day of + # its year. 0001-01-01 is day 306. days = ordinal + 305 - # A century is _DI400Y/4 = 36524.25 days on average, so century c starts - # on day floor(_DI400Y*c/4): the first three centuries of a 400-year - # cycle have 36524 days and the last one 36525. Inverting that, day n - # is in century (4*n + 3) // _DI400Y, and the remainder // 4 is its day - # within the century. + # Centuries average _DI400Y/4 days: three of 36524, then one of 36525. century, rest = divmod(4 * days + 3, _DI400Y) day_of_century = rest // 4 - # Within a century, years follow the same pattern with _DI4Y/4 = 365.25 - # days (three common years, then a leap year; a 36524-day century just - # ends one day early). + # Likewise, years average _DI4Y/4 days: three of 365, then one of 366. year_of_century, rest = divmod(4 * day_of_century + 3, _DI4Y) - day_of_year = rest // 4 # March 1 is day 0 - - # From March on, month lengths follow 31, 30, 31, 30, 31: a 153-day - # block that repeats for March-July, August-December, and then - # January-February, cut short by the end of the year. So - # (5*day_of_year + 2) // 153 is the number of whole months before the - # day, and the remainder // 5 is the day within its month. Adding - # 3*153 = 459 makes March month 3; months 13 and 14 are January and - # February of the next calendar year. + day_of_year = rest // 4 + + # From March, month lengths repeat 31, 30, 31, 30, 31 (153 days). + # 461 = 3*153 + 2 numbers the months from 3 (March) to 14 (February). month, rest = divmod(5 * day_of_year + 461, 153) day = rest // 5 + 1 year = 100 * century + year_of_century diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index e4845c538dfb9db..1d6a4976d7208e7 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -473,44 +473,16 @@ days_before_month(int year, int month) /* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. * - * This follows Neri and Schneider [1]; _ord2ymd() in Lib/_pydatetime.py - * does the same steps. + * Neri and Schneider's algorithm, https://doi.org/10.1002/spe.3172; see + * _ord2ymd() in Lib/_pydatetime.py for an explanation of the steps. * - * February is the irregular month, so we count in a calendar whose years - * start on March 1. Then the leap day, when there is one, is the last day - * of its year, and the long year of each 4-year cycle and the long century - * of each 400-year cycle come last as well. - * - * A century is DI400Y/4 = 36524.25 days on average, so century c starts on - * day floor(DI400Y*c/4); the first three centuries of a 400-year cycle have - * 36524 days and the last one 36525. Inverting that, day n is in century - * (4*n + 3) / DI400Y, and (4*n + 3) % DI400Y / 4 is its day within the - * century. Within a century, years follow the same pattern with - * DI4Y/4 = 365.25 days (three common years, then a leap year; a 36524-day - * century just ends one day early), so the same step with DI4Y gives the - * year and the day within it. - * - * From March on, month lengths follow 31, 30, 31, 30, 31, a 153-day block - * that repeats: March-July, August-December, then January-February (cut - * short by the end of the year). So for day n of the year (March 1 is - * day 0), (5*n + 2) / 153 is the number of whole months before it and - * (5*n + 2) % 153 / 5 is the day within its month. We add 3*153 = 459 so - * that March is month 3; months 13 and 14 are January and February of the - * next calendar year. - * - * All intermediate values fit in 32 bits as long as ordinal is at most - * MAXORDINAL + 2 (iso_to_ymd() can reach 10000-01-02). - * date.fromordinal() handles larger ordinals itself. - * - * [1] Neri C, Schneider L. Euclidean affine functions and their application - * to calendar algorithms. Softw Pract Exper. 2023;53(4):937-970. - * https://doi.org/10.1002/spe.3172 + * The intermediate values only fit in 32 bits for small ordinals; + * iso_to_ymd() passes the largest, MAXORDINAL + 2 (10000-01-02). */ static void ord_to_ymd(int ordinal, int *year, int *month, int *day) { assert(1 <= ordinal && ordinal <= MAXORDINAL + 2); - /* Days since 0000-03-01; 0001-01-01 is 306 days later. */ const uint32_t days = (uint32_t)ordinal + 305; const uint32_t century = (4 * days + 3) / DI400Y; const uint32_t day_of_century = (4 * days + 3) % DI400Y / 4; @@ -3418,11 +3390,8 @@ datetime_date_fromordinal_impl(PyTypeObject *type, int ordinal) ord_to_ymd(ordinal, &year, &month, &day); } else { - /* Out of range: find the year anyway, so new_date_subclass_ex() - * raises the usual "year must be in 1..9999, not N" error. The - * calendar repeats every 400 years (DI400Y days), so convert the - * equivalent date in the first 400-year cycle and add the years - * back. */ + /* Out of range, but compute the year for the error message. + * The calendar repeats every 400 years (DI400Y days). */ int cycles = (ordinal - 1) / DI400Y; ord_to_ymd(ordinal - cycles * DI400Y, &year, &month, &day); year += 400 * cycles; From fe594a99658fb1f86acfeb07ec35b54be65c6466 Mon Sep 17 00:00:00 2001 From: mazalovmx Date: Sun, 15 Nov 2026 09:50:01 -0600 Subject: [PATCH 6/8] gh-161746: Address test review and use ternaries in ord_to_ymd Restore deterministic ordinal boundary tests and revert the unrelated Hypothesis warning workaround. Use Cassio Neri's suggested ternaries for the January/February adjustment; MSVC emits conditional moves in the standalone function, with no consistent API speedup in local measurements. --- Lib/test/datetimetester.py | 35 ++++++++++++--------------- Lib/test/support/hypothesis_helper.py | 9 +------ Modules/_datetimemodule.c | 11 +++------ 3 files changed, 20 insertions(+), 35 deletions(-) diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py index b6c6f4a8bad95e8..a57be7c7f12c005 100644 --- a/Lib/test/datetimetester.py +++ b/Lib/test/datetimetester.py @@ -23,7 +23,6 @@ from test import support from test.support import is_resource_enabled, ALWAYS_EQ, LARGEST, SMALLEST from test.support import os_helper, script_helper -from test.support.hypothesis_helper import hypothesis import datetime as datetime_module from datetime import MINYEAR, MAXYEAR @@ -1435,24 +1434,22 @@ def test_ordinal_conversions(self): self.assertEqual(d, self.theclass.fromordinal(n)) n += 1 - # The ends of the 4-, 100- and 400-year cycles are the tricky cases. - @hypothesis.given(hypothesis.strategies.dates()) - @hypothesis.example(date(1, 1, 1)) - @hypothesis.example(date(4, 2, 29)) - @hypothesis.example(date(4, 12, 31)) - @hypothesis.example(date(100, 2, 28)) - @hypothesis.example(date(100, 3, 1)) - @hypothesis.example(date(100, 12, 31)) - @hypothesis.example(date(400, 2, 29)) - @hypothesis.example(date(400, 12, 31)) - @hypothesis.example(date(401, 1, 1)) - @hypothesis.example(date(2000, 3, 1)) - @hypothesis.example(date(9999, 12, 31)) - def test_ordinal_roundtrip(self, d): - # Rebuild d with the class under test: the strategy and the examples - # may come from the other implementation. - d = self.theclass(d.year, d.month, d.day) - self.assertEqual(self.theclass.fromordinal(d.toordinal()), d) + # Check the first and last days of every month in years at the + # start and the end of the 4-, 100- and 400-year cycles. + for year in (1, 3, 4, 5, 99, 100, 101, 399, 400, 401, 1899, 1900, + 1901, 1999, 2001, 2100, 2399, 2400, 9996, 9999): + isleap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0) + n = self.theclass(year, 1, 1).toordinal() + for month, maxday in zip(range(1, 13), dim): + if month == 2 and isleap: + maxday += 1 + for day, ordinal in (1, n), (maxday, n + maxday - 1): + with self.subTest(year=year, month=month, day=day): + d = self.theclass(year, month, day) + self.assertEqual(d.toordinal(), ordinal) + self.assertEqual(d, self.theclass.fromordinal(ordinal)) + n += maxday + self.assertEqual(n, self.theclass(year, 12, 31).toordinal() + 1) def test_extreme_ordinals(self): a = self.theclass.min diff --git a/Lib/test/support/hypothesis_helper.py b/Lib/test/support/hypothesis_helper.py index 31852d267a287b6..6249ba43f06716a 100644 --- a/Lib/test/support/hypothesis_helper.py +++ b/Lib/test/support/hypothesis_helper.py @@ -1,14 +1,7 @@ import os -import warnings try: - with warnings.catch_warnings(): - # Hypothesis imports typing.AnyStr, which is deprecated. Silence the - # warning so that test.test___all__ can import test modules that use - # Hypothesis. - warnings.filterwarnings("ignore", "'typing.AnyStr' is deprecated", - DeprecationWarning) - import hypothesis + import hypothesis except ImportError: from . import _hypothesis_stubs as hypothesis else: diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index 1d6a4976d7208e7..eb41ebd152986f5 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -491,14 +491,9 @@ ord_to_ymd(int ordinal, int *year, int *month, int *day) const uint32_t m = (5 * day_of_year + 461) / 153; const uint32_t d = (5 * day_of_year + 461) % 153 / 5 + 1; const uint32_t y = 100 * century + year_of_century; - if (m > 12) { /* January or February */ - *year = (int)(y + 1); - *month = (int)(m - 12); - } - else { - *year = (int)y; - *month = (int)m; - } + const uint32_t jan_or_feb = m > 12; + *year = (int) (jan_or_feb ? y + 1 : y); + *month = (int) (jan_or_feb ? m - 12 : m); *day = (int)d; } From 82a3e107a2467a6f06b0f39bedfead26412c5d13 Mon Sep 17 00:00:00 2001 From: mazalovmx Date: Sun, 15 Nov 2026 10:36:05 -0600 Subject: [PATCH 7/8] gh-161746: Revert to if/else for the January/February adjustment Co-Authored-By: Claude Opus 5.5 --- Modules/_datetimemodule.c | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index eb41ebd152986f5..1d6a4976d7208e7 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -491,9 +491,14 @@ ord_to_ymd(int ordinal, int *year, int *month, int *day) const uint32_t m = (5 * day_of_year + 461) / 153; const uint32_t d = (5 * day_of_year + 461) % 153 / 5 + 1; const uint32_t y = 100 * century + year_of_century; - const uint32_t jan_or_feb = m > 12; - *year = (int) (jan_or_feb ? y + 1 : y); - *month = (int) (jan_or_feb ? m - 12 : m); + if (m > 12) { /* January or February */ + *year = (int)(y + 1); + *month = (int)(m - 12); + } + else { + *year = (int)y; + *month = (int)m; + } *day = (int)d; } From 53ba94d947cd086a5612fa805199261c40c325c5 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 15 Nov 2026 18:52:37 +0000 Subject: [PATCH 8/8] Update Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst --- .../2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst index d7bf40d6e73267e..293bf5fb27a7550 100644 --- a/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst +++ b/Misc/NEWS.d/next/Library/2026-11-10-13-28-10.gh-issue-161746.HxgY9R.rst @@ -1,7 +1,3 @@ -Speed up conversion of ordinals to dates in :mod:`datetime` by switching to -the `Neri–Schneider algorithm `__. -:meth:`~datetime.date.fromordinal` is about 15% faster in the C -implementation and about 30% faster in the pure-Python implementation. -Other operations that convert ordinals to dates, such as -:meth:`~datetime.date.fromisocalendar` and :class:`~datetime.timedelta` -arithmetic, also benefit. +Speed up :meth:`datetime.datetime.fromordinal` by about 15% (30% in the +pure-Python implementation) by using the `Neri–Schneider algorithm +`__.