gh-97517: Add documentation links to datetime strftime/strptime docstrings (#138559)

* Add documentation links to datetime strftime/strptime docstrings

- Add links to format codes documentation for all strftime methods
- Add links to format codes documentation for all strptime methods
- Addresses issue #97517

* Update C extension docstrings with format codes documentation

* Regenerate clinic code for updated docstrings

* Add clinic-generated header file for updated docstrings

* Fix docstring spacing consistency in both Python and C files

* Update Lib/_pydatetime.py

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---------

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Lib/_pydatetime.py b/Lib/_pydatetime.py
index ab1b1722b7c254f080fcc38918ce4dcf3085bd83..b6d68f2372850a774efa6e0022e4f1872172d10f 100644 (file)
--- a/Lib/_pydatetime.py
+++ b/Lib/_pydatetime.py
@@ -1072,7 +1072,11 @@ class date:
 
     @classmethod
     def strptime(cls, date_string, format):
-        """Parse string according to the given date format (like time.strptime())."""
+        """Parse string according to the given date format (like time.strptime()).
+
+        For a list of supported format codes, see the documentation:
+            https://docs.python.org/3/library/datetime.html#format-codes
+        """
         import _strptime
         return _strptime._strptime_datetime_date(cls, date_string, format)
 
@@ -1109,6 +1113,8 @@ class date:
         Format using strftime().
 
         Example: "%d/%m/%Y, %H:%M:%S"
+        For a list of supported format codes, see the documentation:
+            https://docs.python.org/3/library/datetime.html#format-codes
         """
         return _wrap_strftime(self, format, self.timetuple())
 
@@ -1456,8 +1462,13 @@ class time:
         return self
 
     @classmethod
+
     def strptime(cls, date_string, format):
-        """Parse string according to the given time format (like time.strptime())."""
+        """Parse string according to the given time format (like time.strptime()).
+
+        For a list of supported format codes, see the documentation:
+            https://docs.python.org/3/library/datetime.html#format-codes
+        """
         import _strptime
         return _strptime._strptime_datetime_time(cls, date_string, format)
 
@@ -1650,6 +1661,9 @@ class time:
     def strftime(self, format):
         """Format using strftime().  The date part of the timestamp passed
         to underlying strftime should not be used.
+
+        For a list of supported format codes, see the documentation:
+            https://docs.python.org/3/library/datetime.html#format-codes
         """
         # The year must be >= 1000 else Python's strftime implementation
         # can raise a bogus exception.
@@ -2198,7 +2212,11 @@ class datetime(date):
 
     @classmethod
     def strptime(cls, date_string, format):
-        """Parse string according to the given date and time format (like time.strptime())."""
+        """Parse string according to the given time format (like time.strptime()).
+
+        For a list of supported format codes, see the documentation:
+            https://docs.python.org/3/library/datetime.html#format-codes
+        """
         import _strptime
         return _strptime._strptime_datetime_datetime(cls, date_string, format)
 

diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c
index 8f1ddf330f3940c7ed9cefce92e51268dfc1a08b..329be68d5b8285d4a4d91d49300713d36a73e40b 100644 (file)
--- a/Modules/_datetimemodule.c
+++ b/Modules/_datetimemodule.c
@@ -3468,12 +3468,15 @@ datetime.date.strptime
     /
 
 Parse string according to the given date format (like time.strptime()).
+
+For a list of supported format codes, see the documentation:
+    https://docs.python.org/3/library/datetime.html#format-codes
 [clinic start generated code]*/
 
 static PyObject *
 datetime_date_strptime_impl(PyTypeObject *type, PyObject *string,
                             PyObject *format)
-/*[clinic end generated code: output=454d473bee2d5161 input=001904ab34f594a1]*/
+/*[clinic end generated code: output=454d473bee2d5161 input=31d57bb789433e99]*/
 {
     PyObject *result;
 
@@ -3608,11 +3611,14 @@ datetime.date.strftime
 Format using strftime().
 
 Example: "%d/%m/%Y, %H:%M:%S".
+
+For a list of supported format codes, see the documentation:
+    https://docs.python.org/3/library/datetime.html#format-codes
 [clinic start generated code]*/
 
 static PyObject *
 datetime_date_strftime_impl(PyObject *self, PyObject *format)
-/*[clinic end generated code: output=6529b70095e16778 input=72af55077e606ed8]*/
+/*[clinic end generated code: output=6529b70095e16778 input=b6fd4a2ded27b557]*/
 {
     /* This method can be inherited, and needs to call the
      * timetuple() method appropriate to self's class.
@@ -4711,12 +4717,15 @@ datetime.time.strptime
     /
 
 Parse string according to the given time format (like time.strptime()).
+
+For a list of supported format codes, see the documentation:
+    https://docs.python.org/3/library/datetime.html#format-codes
 [clinic start generated code]*/
 
 static PyObject *
 datetime_time_strptime_impl(PyTypeObject *type, PyObject *string,
                             PyObject *format)
-/*[clinic end generated code: output=ae05a9bc0241d3bf input=6d0f263a5f94d78d]*/
+/*[clinic end generated code: output=ae05a9bc0241d3bf input=82ba425ecacc54aa]*/
 {
     PyObject *result;
 
@@ -4891,11 +4900,14 @@ datetime.time.strftime
 Format using strftime().
 
 The date part of the timestamp passed to underlying strftime should not be used.
+
+For a list of supported format codes, see the documentation:
+    https://docs.python.org/3/library/datetime.html#format-codes
 [clinic start generated code]*/
 
 static PyObject *
 datetime_time_strftime_impl(PyDateTime_Time *self, PyObject *format)
-/*[clinic end generated code: output=10f65af20e2a78c7 input=541934a2860f7db5]*/
+/*[clinic end generated code: output=10f65af20e2a78c7 input=c4a5bbecd798654b]*/
 {
     PyObject *result;
     PyObject *tuple;
@@ -5787,12 +5799,15 @@ datetime.datetime.strptime
     /
 
 Parse string according to the given date and time format (like time.strptime()).
+
+For a list of supported format codes, see the documentation:
+    https://docs.python.org/3/library/datetime.html#format-codes
 [clinic start generated code]*/
 
 static PyObject *
 datetime_datetime_strptime_impl(PyTypeObject *type, PyObject *string,
                                 PyObject *format)
-/*[clinic end generated code: output=af2c2d024f3203f5 input=d7597c7f5327117b]*/
+/*[clinic end generated code: output=af2c2d024f3203f5 input=ef7807589f1d50e7]*/
 {
     PyObject *result;
 

diff --git a/Modules/clinic/_datetimemodule.c.h b/Modules/clinic/_datetimemodule.c.h
index 7c4bd5503ed56b4a57da4c0ff8cc8ae01ece8579..ee621c150c31e460d5c01850ceeb2989f9baf6f0 100644 (file)
--- a/Modules/clinic/_datetimemodule.c.h
+++ b/Modules/clinic/_datetimemodule.c.h
@@ -371,7 +371,10 @@ PyDoc_STRVAR(datetime_date_strptime__doc__,
 "strptime($type, string, format, /)\n"
 "--\n"
 "\n"
-"Parse string according to the given date format (like time.strptime()).");
+"Parse string according to the given date format (like time.strptime()).\n"
+"\n"
+"For a list of supported format codes, see the documentation:\n"
+"    https://docs.python.org/3/library/datetime.html#format-codes");
 
 #define DATETIME_DATE_STRPTIME_METHODDEF    \
     {"strptime", _PyCFunction_CAST(datetime_date_strptime), METH_FASTCALL|METH_CLASS, datetime_date_strptime__doc__},
@@ -412,7 +415,10 @@ PyDoc_STRVAR(datetime_date_strftime__doc__,
 "\n"
 "Format using strftime().\n"
 "\n"
-"Example: \"%d/%m/%Y, %H:%M:%S\".");
+"Example: \"%d/%m/%Y, %H:%M:%S\".\n"
+"\n"
+"For a list of supported format codes, see the documentation:\n"
+"    https://docs.python.org/3/library/datetime.html#format-codes");
 
 #define DATETIME_DATE_STRFTIME_METHODDEF    \
     {"strftime", _PyCFunction_CAST(datetime_date_strftime), METH_FASTCALL|METH_KEYWORDS, datetime_date_strftime__doc__},
@@ -847,7 +853,10 @@ PyDoc_STRVAR(datetime_time_strptime__doc__,
 "strptime($type, string, format, /)\n"
 "--\n"
 "\n"
-"Parse string according to the given time format (like time.strptime()).");
+"Parse string according to the given time format (like time.strptime()).\n"
+"\n"
+"For a list of supported format codes, see the documentation:\n"
+"    https://docs.python.org/3/library/datetime.html#format-codes");
 
 #define DATETIME_TIME_STRPTIME_METHODDEF    \
     {"strptime", _PyCFunction_CAST(datetime_time_strptime), METH_FASTCALL|METH_CLASS, datetime_time_strptime__doc__},
@@ -970,7 +979,10 @@ PyDoc_STRVAR(datetime_time_strftime__doc__,
 "\n"
 "Format using strftime().\n"
 "\n"
-"The date part of the timestamp passed to underlying strftime should not be used.");
+"The date part of the timestamp passed to underlying strftime should not be used.\n"
+"\n"
+"For a list of supported format codes, see the documentation:\n"
+"    https://docs.python.org/3/library/datetime.html#format-codes");
 
 #define DATETIME_TIME_STRFTIME_METHODDEF    \
     {"strftime", _PyCFunction_CAST(datetime_time_strftime), METH_FASTCALL|METH_KEYWORDS, datetime_time_strftime__doc__},
@@ -1569,7 +1581,10 @@ PyDoc_STRVAR(datetime_datetime_strptime__doc__,
 "strptime($type, string, format, /)\n"
 "--\n"
 "\n"
-"Parse string according to the given date and time format (like time.strptime()).");
+"Parse string according to the given date and time format (like time.strptime()).\n"
+"\n"
+"For a list of supported format codes, see the documentation:\n"
+"    https://docs.python.org/3/library/datetime.html#format-codes");
 
 #define DATETIME_DATETIME_STRPTIME_METHODDEF    \
     {"strptime", _PyCFunction_CAST(datetime_datetime_strptime), METH_FASTCALL|METH_CLASS, datetime_datetime_strptime__doc__},
@@ -2075,4 +2090,4 @@ datetime_datetime___reduce__(PyObject *self, PyObject *Py_UNUSED(ignored))
 {
     return datetime_datetime___reduce___impl((PyDateTime_DateTime *)self);
 }
-/*[clinic end generated code: output=0b8403bc58982e60 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=69658acff6a43ac4 input=a9049054013a1b77]*/