Skip to content

gh-97517: 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-97517: Improve doctrings for datetime parsing methods #20677

Show file tree
Hide file tree
Changes from 1 commit
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
82 changes: 78 additions & 4 deletions Lib/datetime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -925,7 +925,33 @@ def ctime(self):
self._day, self._year)

def strftime(self, fmt):
"Format using strftime()."
"""strftime(fmt) -> date_string
Copy link
Contributor

Choose a reason for hiding this comment

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

The "input -> output" style of doc-strings is only used in functions and class-methods in this module, but not for normal (instance) methods. I don't see that it adds anything in this case (and the others changed by this PR).


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.
Copy link
Contributor

Choose a reason for hiding this comment

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

  1. The argument is named "fmt".
  2. The "Args:" style is different from that currently used in these classes, and adds little in this case with just one argument.
  3. I'm not sure "representation of date_string using format codes" would be clear to someone who hadn't seen this before. It seems to me that an example would be very helpful here.


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.
Copy link
Contributor

Choose a reason for hiding this comment

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

Copied from time.strftime(), I see. This is very nice!

Perhaps here we should omit the codes referring to hours, minutes and seconds?

Also, where would one find more detailed info and the full list of format codes available? Perhaps consider a reference as to where more detailed information may be found, though I'm not sure what that should be. For time.strftime() we have: "Other codes may be available on your platform. See documentation for the C library strftime function."


Returns:
date_string: String representation of the date
Copy link
Contributor

Choose a reason for hiding this comment

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

IMHO these final two lines don't actually add any information.

"""
return _wrap_strftime(self, fmt, self.timetuple())

def __format__(self, fmt):
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)

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.
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