From 91ebaba14c6b82aaeaff7112b3bda570267d99c8 Mon Sep 17 00:00:00 2001 From: Edison Abahurire Date: Fri, 5 Jun 2020 13:24:34 +0300 Subject: [PATCH 1/2] improve doctrings for datetime parsing methods --- Lib/datetime.py | 82 ++++++++++++++++++- .../2020-06-06-15-25-35.bpo-36783.RVoyHF.rst | 2 + 2 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2020-06-06-15-25-35.bpo-36783.RVoyHF.rst diff --git a/Lib/datetime.py b/Lib/datetime.py index 3090978508c921..8e3c74e4160b38 100644 --- a/Lib/datetime.py +++ b/Lib/datetime.py @@ -925,7 +925,33 @@ def ctime(self): self._day, self._year) def strftime(self, fmt): - "Format using strftime()." + """strftime(fmt) -> date_string + + Return a string from the date parsed according to format. + Format codes referring to hours, minutes or seconds will see 0 values. + + Args: + format: representation of date_string 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: + date_string: String representation of the date + """ return _wrap_strftime(self, fmt, self.timetuple()) def __format__(self, fmt): @@ -1445,8 +1471,25 @@ 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. + """strftime(fmt) -> time_string + + Return a string of the time parsed according to format. + Format codes referring to year, month or days will see 0 values. + + Args: + fmt: representation of time using format codes. + + Commonly used format codes: + %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. + + Returns: + time_string: String representation of time """ # The year must be >= 1000 else Python's strftime implementation # can raise a bogus exception. @@ -1944,7 +1987,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. From 27f5a98e7f877f8614d828d7d6c1426c0cde892d Mon Sep 17 00:00:00 2001 From: Tal Einat <532281+taleinat@users.noreply.github.com> Date: Thu, 20 Jan 2022 23:57:47 +0200 Subject: [PATCH 2/2] further improve doc-strings, add to datetime.datetime and add to _datetimemodule Signed-off-by: Tal Einat <532281+taleinat@users.noreply.github.com> --- Lib/datetime.py | 102 +++++++++++++++++++++----------------- Modules/_datetimemodule.c | 52 ++++++++++++++++++- 2 files changed, 107 insertions(+), 47 deletions(-) diff --git a/Lib/datetime.py b/Lib/datetime.py index 9eebd6089bc5a0..32686710a2d8e9 100644 --- a/Lib/datetime.py +++ b/Lib/datetime.py @@ -925,32 +925,23 @@ def ctime(self): self._day, self._year) def strftime(self, fmt): - """strftime(fmt) -> date_string - - Return a string from the date parsed according to format. - Format codes referring to hours, minutes or seconds will see 0 values. - - Args: - format: representation of date_string 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: - date_string: String representation of the date + """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()) @@ -1472,25 +1463,22 @@ def fromisoformat(cls, time_string): def strftime(self, fmt): - """strftime(fmt) -> time_string - - Return a string of the time parsed according to format. - Format codes referring to year, month or days will see 0 values. - - Args: - fmt: representation of time using format codes. - - Commonly used format codes: - %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. - - Returns: - time_string: String representation of time + """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. @@ -1937,6 +1925,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. diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c index fda8401b84cd15..c3f42d741f8c65 100644 --- a/Modules/_datetimemodule.c +++ b/Modules/_datetimemodule.c @@ -3506,7 +3506,21 @@ static PyMethodDef date_methods[] = { PyDoc_STR("Return ctime() style string.")}, {"strftime", (PyCFunction)(void(*)(void))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.")}, @@ -4674,7 +4688,20 @@ static PyMethodDef time_methods[] = { "'milliseconds' and 'microseconds'.\n")}, {"strftime", (PyCFunction)(void(*)(void))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.")}, @@ -6364,6 +6391,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().")},