gh-136571: Convert more code in datetime to Argument Clinic

serhiy-storchaka · serhiy-storchaka · commit 0b5a23aadc26 · 2025-07-12T14:15:49.000+03:00
This adds signatures for some classes and methods.

date.fromisocalendar() can now raise OverflowError for arguments that
don't fit in the C int.
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
@@ -2383,7 +2383,7 @@ locations where different offsets are used in different days of the year or
 where historical changes have been made to civil time.
 
 
-.. class:: timezone(offset, name=None)
+.. class:: timezone(offset[, name])
 
   The *offset* argument must be specified as a :class:`timedelta`
   object representing the difference between the local time and UTC. It must
diff --git a/Lib/_pydatetime.py b/Lib/_pydatetime.py
@@ -1083,7 +1083,7 @@ def fromisocalendar(cls, year, week, day):
 
     @classmethod
     def strptime(cls, date_string, format):
-        """Parse a date string according to the given format (like time.strptime())."""
+        """Parse string according to the given date format (like time.strptime())."""
         import _strptime
         return _strptime._strptime_datetime_date(cls, date_string, format)
 
@@ -1310,7 +1310,7 @@ def __reduce__(self):
 
 
 class tzinfo:
-    """Abstract base class for time zone info classes.
+    """Abstract base class for time zone info objects.
 
     Subclasses must override the tzname(), utcoffset() and dst() methods.
     """
@@ -1468,7 +1468,7 @@ def __new__(cls, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold
 
     @classmethod
     def strptime(cls, date_string, format):
-        """string, format -> new time parsed from a string (like time.strptime())."""
+        """Parse string according to the given time format (like time.strptime())."""
         import _strptime
         return _strptime._strptime_datetime_time(cls, date_string, format)
 
@@ -1776,7 +1776,7 @@ def __reduce__(self):
 
 
 class datetime(date):
-    """datetime(year, month, day[, hour[, minute[, second[, microsecond[,tzinfo]]]]])
+    """A combination of a date and a time.
 
     The year, month and day arguments are required. tzinfo may be None, or an
     instance of a tzinfo subclass. The remaining arguments may be ints.
@@ -2209,7 +2209,7 @@ def __str__(self):
 
     @classmethod
     def strptime(cls, date_string, format):
-        'string, format -> new datetime parsed from a string (like time.strptime()).'
+        """Parse string according to the given date and time format (like time.strptime())."""
         import _strptime
         return _strptime._strptime_datetime_datetime(cls, date_string, format)
 
@@ -2435,6 +2435,8 @@ def _isoweek1monday(year):
 
 
 class timezone(tzinfo):
+    """Fixed offset from UTC implementation of tzinfo."""
+
     __slots__ = '_offset', '_name'
 
     # Sentinel value to disallow None
diff --git a/Lib/test/datetimetester.py b/Lib/test/datetimetester.py
@@ -2147,14 +2147,20 @@ def test_fromisocalendar_value_errors(self):
             (10000, 1, 1),
             (0, 1, 1),
             (9999999, 1, 1),
+        ]
+        for isocal in isocals:
+            with self.subTest(isocal=isocal):
+                with self.assertRaises(ValueError):
+                    self.theclass.fromisocalendar(*isocal)
+
+        isocals = [
             (2<<32, 1, 1),
             (2019, 2<<32, 1),
             (2019, 1, 2<<32),
         ]
-
         for isocal in isocals:
             with self.subTest(isocal=isocal):
-                with self.assertRaises(ValueError):
+                with self.assertRaises((ValueError, OverflowError)):
                     self.theclass.fromisocalendar(*isocal)
 
     def test_fromisocalendar_type_errors(self):
@@ -2301,7 +2307,7 @@ def test_isoformat_timezone(self):
             dt = dt_base.replace(tzinfo=tzi)
             exp = exp_base + exp_tz
             with self.subTest(tzi=tzi):
-                assert dt.isoformat() == exp
+                self.assertEqual(dt.isoformat(), exp)
 
     def test_format(self):
         dt = self.theclass(2007, 9, 10, 4, 5, 1, 123)
@@ -3349,7 +3355,7 @@ def test_fromisoformat_timezone(self):
 
             with self.subTest(tstr=dtstr):
                 dt_rt = self.theclass.fromisoformat(dtstr)
-                assert dt == dt_rt, dt_rt
+                self.assertEqual(dt_rt, dt)
 
     def test_fromisoformat_separators(self):
         separators = [
@@ -3865,7 +3871,7 @@ def test_isoformat_timezone(self):
             t = t_base.replace(tzinfo=tzi)
             exp = exp_base + exp_tz
             with self.subTest(tzi=tzi):
-                assert t.isoformat() == exp
+                self.assertEqual(t.isoformat(), exp)
 
     def test_1653736(self):
         # verify it doesn't accept extra keyword arguments
@@ -4350,7 +4356,7 @@ def utcoffset(self, t):
                     elif x is d2:
                         expected = -1
                     else:
-                        assert y is d2
+                        self.assertIs(y, d2)
                         expected = 1
                     self.assertEqual(got, expected)
 
@@ -4678,7 +4684,7 @@ def test_fromisoformat_timezone(self):
 
             with self.subTest(tstr=tstr):
                 t_rt = self.theclass.fromisoformat(tstr)
-                assert t == t_rt
+                self.assertEqual(t_rt, t)
 
     def test_fromisoformat_timespecs(self):
         time_bases = [
@@ -5515,7 +5521,7 @@ def utcoffset(self, t):
                 elif x is d2:
                     expected = timedelta(minutes=(11-59)-0)
                 else:
-                    assert y is d2
+                    self.assertIs(y, d2)
                     expected = timedelta(minutes=0-(11-59))
                 self.assertEqual(got, expected)
 
diff --git a/Lib/test/test_inspect/test_inspect.py b/Lib/test/test_inspect/test_inspect.py
@@ -5830,6 +5830,19 @@ def test_collections_abc_module_has_signatures(self):
         import collections.abc
         self._test_module_has_signatures(collections.abc)
 
+    def test_datetime_module_has_signatures(self):
+        import datetime
+        no_signature = {'tzinfo'}
+        unsupported_signature = {'timezone'}
+        methods_unsupported_signature = {
+            'date': {'replace'},
+            'time': {'replace'},
+            'datetime': {'replace', 'combine'},
+        }
+        self._test_module_has_signatures(datetime,
+                no_signature, unsupported_signature,
+                methods_unsupported_signature=methods_unsupported_signature)
+
     def test_errno_module_has_signatures(self):
         import errno
         self._test_module_has_signatures(errno)
diff --git a/Misc/NEWS.d/next/Library/2025-07-12-14-15-47.gh-issue-136571.muHmBv.rst b/Misc/NEWS.d/next/Library/2025-07-12-14-15-47.gh-issue-136571.muHmBv.rst
@@ -0,0 +1,2 @@
+:meth:`datetime.date.fromisocalendar` can now raise OverflowError for out of
+range arguments.
diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c
diff --git a/Modules/clinic/_datetimemodule.c.h b/Modules/clinic/_datetimemodule.c.h

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+:meth:`datetime.date.fromisocalendar` can now raise OverflowError for out of
	`2`	`+range arguments.`