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().")}, pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy