diff --git a/Lib/datetime.py b/Lib/datetime.py index 01742680a95bb6..8d2f196dca6851 100644 --- a/Lib/datetime.py +++ b/Lib/datetime.py @@ -1033,10 +1033,23 @@ def ctime(self): self._day, self._year) def strftime(self, fmt): - """ - Format using strftime(). - - Example: "%d/%m/%Y, %H:%M:%S" + """Convert to a string in the given format via time.strftime(). + + Formatting directives referring to hours, minutes or seconds + will use zero. + + Commonly used formatting directives: + %Y Year with century as a decimal number. + %m Month as a decimal number [01,12]. + %d Day of the month as a decimal number [01,31]. + %a Locale's abbreviated weekday name. + %A Locale's full weekday name. + %b Locale's abbreviated month name. + %B Locale's full month name. + %c Locale's appropriate date and time representation. + + For a complete list and detailed descriptions of formatting + directives, see the library reference manual. """ return _wrap_strftime(self, fmt, self.timetuple()) @@ -1555,8 +1568,22 @@ 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. + """Convert to a string in the given format via time.strftime(). + + Formatting directives referring to years will use 1900, and + those referring to months or days will use 1. + + Commonly used formatting directives: + %H Hour (24-hour clock) as a decimal number [00,23]. + %M Minute as a decimal number [00,59]. + %S Second as a decimal number [00,61]. + %z Time zone offset from UTC. + %c Locale's appropriate date and time representation. + %I Hour (12-hour clock) as a decimal number [01,12]. + %p Locale's equivalent of either AM or PM. + + For a complete list and detailed descriptions of formatting + directives, see the library reference manual. """ # The year must be >= 1000 else Python's strftime implementation # can raise a bogus exception. @@ -2009,6 +2036,30 @@ def ctime(self): self._hour, self._minute, self._second, self._year) + def strftime(self, fmt): + """Convert to a string in the given format via time.strftime(). + + Commonly used formatting directives: + %Y Year with century as a decimal number. + %m Month as a decimal number [01,12]. + %d Day of the month as a decimal number [01,31]. + %H Hour (24-hour clock) as a decimal number [00,23]. + %M Minute as a decimal number [00,59]. + %S Second as a decimal number [00,61]. + %z Time zone offset from UTC. + %a Locale's abbreviated weekday name. + %A Locale's full weekday name. + %b Locale's abbreviated month name. + %B Locale's full month name. + %c Locale's appropriate date and time representation. + %I Hour (12-hour clock) as a decimal number [01,12]. + %p Locale's equivalent of either AM or PM. + + For a complete list and detailed descriptions of formatting + directives, see the library reference manual. + """ + return _wrap_strftime(self, fmt, self.timetuple()) + def isoformat(self, sep='T', timespec='auto'): """Return the time formatted according to ISO. @@ -2061,7 +2112,38 @@ def __str__(self): @classmethod def strptime(cls, date_string, format): - 'string, format -> new datetime parsed from a string (like time.strptime()).' + """strptime(date_string, format) -> datetime object + + Return a datetime object from the date_string, + parsed according to format. + + Args: + date_string: string containing the date. + format: representation of datetime using format codes. + + Commonly used format codes: + %Y Year with century as a decimal number. + %m Month as a decimal number [01,12]. + %d Day of the month as a decimal number [01,31]. + %H Hour (24-hour clock) as a decimal number [00,23]. + %M Minute as a decimal number [00,59]. + %S Second as a decimal number [00,61]. + %z Time zone offset from UTC. + %a Locale's abbreviated weekday name. + %A Locale's full weekday name. + %b Locale's abbreviated month name. + %B Locale's full month name. + %c Locale's appropriate date and time representation. + %I Hour (12-hour clock) as a decimal number [01,12]. + %p Locale's equivalent of either AM or PM. + + Returns: + Datetime object + + Raises: + ValueError: If the date_string and format can’t be parsed by + time.strptime() or if it returns a value which isn’t a time tuple. + """ import _strptime return _strptime._strptime_datetime(cls, date_string, format) diff --git a/Misc/NEWS.d/next/Documentation/2020-06-06-15-25-35.bpo-36783.RVoyHF.rst b/Misc/NEWS.d/next/Documentation/2020-06-06-15-25-35.bpo-36783.RVoyHF.rst new file mode 100644 index 00000000000000..a82f08b38f8903 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2020-06-06-15-25-35.bpo-36783.RVoyHF.rst @@ -0,0 +1,2 @@ +Improve docstring of :class:`datetime` methods :func:`strftime` and +:func:`strptime`. Enhanced by Edison Abahurire. diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index d86418af0dc1a8..b918fb8795ac33 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -3591,7 +3591,21 @@ static PyMethodDef date_methods[] = { PyDoc_STR("Return ctime() style string.")}, {"strftime", _PyCFunction_CAST(date_strftime), METH_VARARGS | METH_KEYWORDS, - PyDoc_STR("format -> strftime() style string.")}, + PyDoc_STR( + "Convert to a string in the given format via time.strftime().\n\n" + "Formatting directives referring to hours, minutes or seconds\n" + "will use zero.\n\n" + "Commonly used formatting directives:\n" + " %Y Year with century as a decimal number.\n" + " %m Month as a decimal number [01,12].\n" + " %d Day of the month as a decimal number [01,31].\n" + " %a Locale's abbreviated weekday name.\n" + " %A Locale's full weekday name.\n" + " %b Locale's abbreviated month name.\n" + " %B Locale's full month name.\n" + " %c Locale's appropriate date and time representation.\n\n" + "For a complete list and detailed descriptions of formatting\n" + "directives, see the library reference manual.")}, {"__format__", (PyCFunction)date_format, METH_VARARGS, PyDoc_STR("Formats self with strftime.")}, @@ -4745,7 +4759,20 @@ static PyMethodDef time_methods[] = { "'milliseconds' and 'microseconds'.\n")}, {"strftime", _PyCFunction_CAST(time_strftime), METH_VARARGS | METH_KEYWORDS, - PyDoc_STR("format -> strftime() style string.")}, + PyDoc_STR( + "Convert to a string in the given format via time.strftime().\n\n" + "Formatting directives referring to years will use 1900, and\n" + "those referring to months or days will use 1.\n\n" + "Commonly used formatting directives:\n" + " %H Hour (24-hour clock) as a decimal number [00,23].\n" + " %M Minute as a decimal number [00,59].\n" + " %S Second as a decimal number [00,61].\n" + " %z Time zone offset from UTC.\n" + " %c Locale's appropriate date and time representation.\n" + " %I Hour (12-hour clock) as a decimal number [01,12].\n" + " %p Locale's equivalent of either AM or PM.\n\n" + "For a complete list and detailed descriptions of formatting\n" + "directives, see the library reference manual.")}, {"__format__", (PyCFunction)date_format, METH_VARARGS, PyDoc_STR("Formats self with strftime.")}, @@ -6572,6 +6599,27 @@ static PyMethodDef datetime_methods[] = { {"ctime", (PyCFunction)datetime_ctime, METH_NOARGS, PyDoc_STR("Return ctime() style string.")}, + {"strftime", (PyCFunction)(void(*)(void))date_strftime, METH_VARARGS | METH_KEYWORDS, + PyDoc_STR( + "Convert to a string in the given format via time.strftime().\n\n" + "Commonly used formatting directives:\n" + " %Y Year with century as a decimal number.\n" + " %m Month as a decimal number [01,12].\n" + " %d Day of the month as a decimal number [01,31].\n" + " %H Hour (24-hour clock) as a decimal number [00,23].\n" + " %M Minute as a decimal number [00,59].\n" + " %S Second as a decimal number [00,61].\n" + " %z Time zone offset from UTC.\n" + " %a Locale's abbreviated weekday name.\n" + " %A Locale's full weekday name.\n" + " %b Locale's abbreviated month name.\n" + " %B Locale's full month name.\n" + " %c Locale's appropriate date and time representation.\n" + " %I Hour (12-hour clock) as a decimal number [01,12].\n" + " %p Locale's equivalent of either AM or PM.\n\n" + "For a complete list and detailed descriptions of formatting\n" + "directives, see the library reference manual.")}, + {"timetuple", (PyCFunction)datetime_timetuple, METH_NOARGS, PyDoc_STR("Return time tuple, compatible with time.localtime().")},