gh-97517: Improve docstrings for strptime and strftime methods in datetime module

Lib/datetime.py

@@ -1025,15 +1025,82 @@ def __repr__(self):
 
 
     def ctime(self):
-        "Return ctime() style string."
+        """Return ctime() style string.
+
+        >>> date(2001, 10, 5).ctime()
+        'Fri Oct  5 00:00:00 2001'
+        """
         weekday = self.toordinal() % 7 or 7
         return "%s %s %2d 00:00:00 %04d" % (
             _DAYNAMES[weekday],
             _MONTHNAMES[self._month],
             self._day, self._year)
 
     def strftime(self, fmt):
-        "Format using strftime()."
+        """Format date or datetime given the format string `fmt`
+
+        The following format codes can be used within the format string. Entries
+        marked with * are localised.
+
+        * %f microseconds as a zero-padded 6 digit decimal
+
+        * %S seconds (zero-padded)
+
+        * %M minutes (zero-padded)
+
+        * %H hour (24-hour clock)
+
+        * %I hour (12-hour clock)
+
+        * %p AM-PM*
+
+        * %z UTC offset in the form (+-)HHMM[SS[.ffffff]]
+
+        * %Z time zone name
+
+        * %a abbreviated weekday*
+
+        * %A full weekday*
+
+        * %w weekday as decimal (Sunday = 0 through to Saturday = 6)
+
+        * %u ISO 8601 weekday where 1 is Monday (1 - 7)
+
+        * %d day of month as zero-padded decimal (01 - 31)
+
+        * %m month as a zero-padded decimal (01 - 12)
+
+        * %b abbreviated month*
+
+        * %B full month*
+
+        * %j day of the year as a zero-padded decimal (001 - 3666)
+
+        * %U week number of the year with Sunday as the first day (00 - 53)
+
+        * %W week number of the year with Monday as the first day (00 - 53)
+
+        * %V ISO 8601 week number (01 - 53)
+
+        * %y year without century (00, 01, ...)
+
+        * %Y year with century (0001, 0002, ..., 2000, ...)
+
+        * %G ISO 8601 year with century
+
+        * %X locale's appropriate time representation
+
+        * %x locale's appropriate date representation
+
+        * %c date and time in locale's appropriate format
+
+        * %% the literal '%' character
+
+        >>> datetime(2010, 1, 1).strftime('%d %b %Y')
+        '01 Jan 2010'
+        """
+        # Documentation above should keep dot points updated with
+        # datetime.strptime, as the same escape sequences are used.
         return _wrap_strftime(self, fmt, self.timetuple())
 
     def __format__(self, fmt):
@@ -1551,9 +1618,40 @@ def fromisoformat(cls, time_string):
 
 
     def strftime(self, fmt):
-        """Format using strftime().  The date part of the timestamp passed
-        to underlying strftime should not be used.
+        """Format time given the format string `fmt`
+
+        The following format codes can be used within the format string. Entries
+        marked with * are localised.
+
+        * %f microseconds as a zero-padded 6 digit decimal
+
+        * %S seconds (zero-padded)
+
+        * %M minutes (zero-padded)
+
+        * %H hour (24-hour clock)
+
+        * %I hour (12-hour clock)
+
+        * %p AM-PM*
+
+        * %z UTC offset in the form (+-)HHMM[SS[.ffffff]]
+
+        * %Z time zone name
+
+        * %X locale's appropriate time representation
+
+        * %% the literal '%' character
+
+        The date part of the timestamp passed to underlying strftime should not
+        be used.
+
+        >>> time(10, 42).strftime('%M:%S')
+        '10:42'
         """
+        # Documentation above should keep dot points updated with
+        # datetime.strftime, as a subset of the same escape sequences are used.
+
         # The year must be >= 1000 else Python's strftime implementation
         # can raise a bogus exception.
         timetuple = (1900, 1, 1,
@@ -2057,7 +2155,71 @@ def __str__(self):
 
     @classmethod
     def strptime(cls, date_string, format):
-        'string, format -> new datetime parsed from a string (like time.strptime()).'
+        """Parses a datetime from a string given a format specification, much
+        like strptime() in the time module.
+
+        The following format codes can be used within the format string. Entries
+        marked with * are localised.
+
+        * %f microseconds as a zero-padded 6 digit decimal
+
+        * %S seconds (zero-padded)
+
+        * %M minutes (zero-padded)
+
+        * %H hour (24-hour clock)
+
+        * %I hour (12-hour clock)
+
+        * %p AM-PM*
+
+        * %z UTC offset in the form (+-)HHMM[SS[.ffffff]]
+
+        * %Z time zone name
+
+        * %a abbreviated weekday*
+
+        * %A full weekday*
+
+        * %w weekday as decimal (Sunday = 0 through to Saturday = 6)
+
+        * %u ISO 8601 weekday where 1 is Monday (1 - 7)
+
+        * %d day of month as zero-padded decimal (01 - 31)
+
+        * %m month as a zero-padded decimal (01 - 12)
+
+        * %b abbreviated month*
+
+        * %B full month*
+
+        * %j day of the year as a zero-padded decimal (001 - 3666)
+
+        * %U week number of the year with Sunday as the first day (00 - 53)
+
+        * %W week number of the year with Monday as the first day (00 - 53)
+
+        * %V ISO 8601 week number (01 - 53)
+
+        * %y year without century (00, 01, ...)
+
+        * %Y year with century (0001, 0002, ..., 2000, ...)
+
+        * %G ISO 8601 year with century
+
+        * %X locale's appropriate time representation
+
+        * %x locale's appropriate date representation
+
+        * %c date and time in locale's appropriate format
+
+        * %% the literal '%' character
+
+        >>> datetime.strptime('01 Jan 2010', '%d %b %Y')
+        datetime.datetime(2010, 1, 1, 0, 0)
+        """
+        # Documentation above should keep dot points updated with
+        # datetime.strftime, as the same escape sequences are used.
         import _strptime
         return _strptime._strptime_datetime(cls, date_string, format)