Approx 1.5x speedup in weekday in Datetime using pre computed odd days

[utkarsh-naman]

gh-NNNNNN: Optimize date.weekday() using precomputed odd days

Summary

Summary

This PR optimizes the weekday calculation in datetime by using precomputed odd-day values for months and a reduced calculation for the number of odd days before a given year.

The optimization is implemented in both the pure-Python implementation and the C implementation:

• Lib/_pydatetime.py
• Modules/_datetimemodule.c

The existing weekday behavior and Gregorian calendar rules are preserved.

Implementation

The optimization introduces a lookup table containing the number of odd days before each month:

January    0
February   3
March      3
April      6
May        1
June       4
July       6
August     2
September  5
October    0
November   3
December   5

The number of odd days before the start of a year is then computed using the Gregorian 400-year cycle rather than calculating the full number of days before the year.

For dates after February in a leap year, the additional leap day is added to the ordinal calculation.

The resulting weekday calculation is:

odd days before year
+ odd days before month
+ day
+ leap-day adjustment

followed by modulo 7.

The corresponding logic has been added to both _pydatetime.py and _datetimemodule.c.
The C implementation similarly adds the month lookup table, the optimized year calculation, and uses the resulting ordinal in weekday().

Correctness

The optimized calculation was exhaustively tested against an independent Gregorian weekday implementation using every valid date in the supported datetime range.

0001-01-01 through 9999-12-31

Results:

Years tested : 9,999
Dates tested : 3,652,059
Mismatches   : 0
Result       : ALL DATES MATCH

The reference implementation used for the verification was Sakamoto's Gregorian weekday algorithm, which is independent of the odd-day implementation.

The exhaustive test therefore covers:

• Ordinary years
• Leap years
• Century years
• Years divisible by 400
• February 29
• All month boundaries
• The minimum supported year
• The maximum supported year

Performance

The purpose of this change is to reduce the arithmetic required for weekday calculation by replacing repeated day-count calculations with precomputed month values and reduced year arithmetic.

The performance claim should be based on a pyperf benchmark of the actual CPython implementation.

Testing

An independent exhaustive C test was used to verify the weekday calculation.

The complete supported Gregorian range was tested:

0001-01-01 → 9999-12-31

All 3,652,059 valid dates matched the independent reference implementation.

====================================================
                    SUCCESS
====================================================

Years tested : 9999
Dates tested : 3652059
Expected     : 3652059
Result       : ALL DATES MATCH

Files changed

• Lib/_pydatetime.py
• Modules/_datetimemodule.c

Backward compatibility

This change does not modify the public datetime API or Gregorian calendar behavior.

date.weekday() continues to return:

Monday    = 1
Tuesday   = 2
Wednesday = 3
Thursday  = 4
Friday    = 5
Saturday  = 6
Sunday    = 7

Only the internal calculation used to obtain the weekday has been changed.

Motivation

weekday() is a small, frequently used operation, so reducing the arithmetic required for the calendar calculation can improve its execution time while retaining the existing behavior.

The optimization also takes advantage of the fact that the Gregorian calendar repeats every 400 years:

400 years = 146,097 days
146,097 % 7 = 0

Therefore, complete 400-year cycles do not affect the resulting weekday.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[picnixz]

Please create an issue first to discuss this and show that we have real improvements in usercode. I do not think this one js necessary