Skip to content

gh-84823: Improve doctrings for datetime parsing methods #20677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

gh-84823: Improve doctrings for datetime parsing methods #20677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
91ebaba
improve doctrings for datetime parsing methods
Jun 5, 2020
ab411af
Merge branch 'main' into bpo-40643
taleinat Jan 20, 2022
27f5a98
further improve doc-strings, add to datetime.datetime and add to _dat…
taleinat Jan 20, 2022
ad4a503
Merge branch 'main' into bpo-40643
edison12a May 19, 2022
601f012
Merge branch 'main' into bpo-40643
AlexWaygood Oct 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 89 additions & 7 deletions Lib/datetime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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().
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these aren't supposed to be time.strftime(), I think we want to directly reference :manpage:`strftime(3)`. Or at least strftime(3) (I guess these docstrings aren't destined for Sphinx, so probably just strftime(3) is most appropriate)


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())

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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)

Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Documentation/2020-06-06-15-25-35.bpo-36783.RVoyHF.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Improve docstring of :class:`datetime` methods :func:`strftime` and
:func:`strptime`. Enhanced by Edison Abahurire.
52 changes: 50 additions & 2 deletions Modules/_datetimemodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here as well.

"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.")},
Expand Down Expand Up @@ -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.")},
Expand Down Expand Up @@ -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().")},

Expand Down