classification
Title: format codes in time.strptime docstrings
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: belopolsky Nosy List: belopolsky, catherine, christian.heimes, cvrebert, docs@python, eric.araujo, ezio.melotti, mikehoy, python-dev
Priority: normal Keywords: easy, patch

Created on 2010-08-20 15:49 by catherine, last changed 2012-12-01 22:01 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
issue9650-format-codes.diff mikehoy, 2012-09-30 15:44 Add Format Codes to timemodule.c review
issue9650-format-codes_v2.diff mikehoy, 2012-09-30 19:04 Removed non-ascii apostrophes review
issue9650-format-codes_v3.diff mikehoy, 2012-09-30 21:44 strptime and %I, %p review
Messages (23)
msg114427 - (view) Author: Catherine Devlin (catherine) Date: 2010-08-20 15:49
Is there any reason not to include the strftime formatting codes in the docstrings of time.strftime and time.strptime? 

>>> print time.strftime.__doc__
strftime(format[, tuple]) -> string

Convert a time tuple to a string according to a format specification.
See the library reference manual for formatting codes. When the time tuple is not present, current time as returned by localtime() is used.


Sending users to look up such a basic, frequently-used, hard-to-remember set of codes in the docs every single time seems unfriendly.  Even a tightly abbreviated list would be very convenient.
msg114428 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-08-20 16:24
+1


These are apparently so commonly looked up that there are even two websites dedicated to these options: http://strftime.org/ and http://strfti.me/. Even Sauce Labs put the format options on the side of the coffee mugs they handed out at PyCon 2010 :)
msg114431 - (view) Author: Skip Montanaro (skip.montanaro) * Date: 2010-08-20 17:10
There is the non-zero cost of keeping two copies of that bit of
information in-sync with each other (and the code).

If I execute "pydoc time" I get a link to the online module
docs.  It's not there when I execute "pydoc time.strftime".
Perhaps pydoc should be modified to always include a link
to the defining module even when the user asked for docs 
for something other than a module.
msg114436 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-20 18:01
> Is there any reason not to include the strftime formatting codes
> in the docstrings of time.strftime and time.strptime? 

I believe the reason is that time.strftime behavior is platform dependent, so "man strftime" is likely to produce more relevant documentation than "pydoc time.strftime".  Python manual <http://docs.python.org/library/time.html?#time.strftime> lists ANSI C codes, but warns that "Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C."  It is likely that there are platforms where ANSI C subset does not behave in a fully compliant manner.
msg114437 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-20 18:02
> there are even two websites dedicated to these options:
> http://strftime.org/ ...

Note the source at one of these sites:

"Source: Python’s strftime documentation." :-)
msg115011 - (view) Author: Catherine Devlin (catherine) Date: 2010-08-26 17:48
> There is the non-zero cost of keeping two copies of that bit of
> information in-sync with each other (and the code).

That's true, but how often do the strftime format codes change?  I'd be happy to personally volunteer to keep them in synch.  I suspect it would take me half an hour once or even twice per decade.

> I believe the reason is that time.strftime behavior is platform dependent, so "man strftime" is likely to produce more relevant documentation than "pydoc time.strftime".

So everything I've written with strftime is not cross-platform after all?  Eek.

Anyway, why couldn't the docstring do the same thing the Python docs do - report the ANSI codes, and mention that platform-specific variations are possible?

Alternately, simply including a suggestion to ``man strftime`` in the docs would be a good start, since I had no idea about that (and I doubt I'm the only one).  Of course, it's useless advice for Windows users.

> Note the source at one of these sites:

> "Source: Python’s strftime documentation." :-)

Of course - the point is that people are feeling enough pain in drilling down to the right place in the Python documentation that a convenient designated URL seems attractive by comparison.
msg115028 - (view) Author: Skip Montanaro (skip.montanaro) * Date: 2010-08-26 21:27
Catherine,

Did my suggestion to alter pydoc output so it always contains a link to the
enclosing module's documentation not seem like a reasonable compromise?

Another problem with embedding the format codes in the docstring is that it
opens up a Pandora's box of other stuff that might be reasonable to include
in other docstrings, but should probably just be documented in one place
(perhaps with references elsewhere).  For example, maybe we should add the
list of signals to the docstrings for signal.signal and os.kill (pretty
platform-dependent) or add all the format possibilities to the docstring for
the format() builtin (brand new and probably not well-known to very many
users).  I'm sure there are other candidates.  It can be difficult to know
where to draw the line.

Skip
msg115215 - (view) Author: Catherine Devlin (catherine) Date: 2010-08-30 13:49
> Did my suggestion to alter pydoc output so it always contains a link to the
> enclosing module's documentation not seem like a reasonable compromise?

I actually don't understand how that would help.  The ``pydoc time`` output doesn't include any information about the formatting codes (at least, on my system).

Also, ``pydoc`` isn't available on Windows systems, is it?  It isn't on mine; is that a quirk of my setup?

> Another problem with embedding the format codes in the docstring is that it
> opens up a Pandora's box of other stuff that might be reasonable to include
> in other docstrings, but should probably just be documented in one place
> (perhaps with references elsewhere).  For example, maybe we should add the
> list of signals to the docstrings for signal.signal and os.kill (pretty
> platform-dependent) or add all the format possibilities to the docstring for
> the format() builtin (brand new and probably not well-known to very many
> users).  I'm sure there are other candidates.  It can be difficult to know
> where to draw the line.

Yes, certainly, in one place - but isn't it logical for the docstring to be that one place?  Universal convenient access, and the least risk that it will get out of synch with the code.

Here's where I would suggest drawing the line: if the method is unusable without the information, and it's not easy to guess or remember, and it's relatively concise, it should be in the docstring.

Is that a Pandora's box or a set of good suggestions?  :)  Probably not stuff that is strongly platform-dependent, but for format(), for example, I think that's a good idea.  I don't think there's anything wrong with setting a precedent that could lead to more useful docstrings in several different places.

Anyway, I would settle for a suggestion in the docstring to run ``man strftime``, but only if there's some Windows equivalent; does anybody know of one?
msg115219 - (view) Author: Skip Montanaro (skip.montanaro) * Date: 2010-08-30 14:42
>> Did my suggestion to alter pydoc output so it always contains a link
    >> to the enclosing module's documentation not seem like a reasonable
    >> compromise?

    Catherine> I actually don't understand how that would help.  The ``pydoc
    Catherine> time`` output doesn't include any information about the
    Catherine> formatting codes (at least, on my system).

No, but it does include a link to the full documentation for the time
module, so should you need more than is in the docstring, in theory
everything you might want would only be one or two clicks away.

    Catherine> Also, ``pydoc`` isn't available on Windows systems, is it?
    Catherine> It isn't on mine; is that a quirk of my setup?

You can fire up a documentation server using

    python -m pydoc -g

which starts an HTTP server available to dispense documentation for
everything in your PYTHONPATH.  You can search for "strftime" there, and
after a fairly long pause it will present you with a link you can click to
get the time module docs.  (I think there is a bug in the way it handles
errors during import of the various modules.)

Alternatively, click the "open browser" button and you will be directed to
the front page of the content it serves.  The resulting user interface is
fairly crude, but if you search for "time" (it's in the lib-dynload section)
and click the link provided, it pops up the pydoc documentation for the time
module.  From there you can click the Module Docs link in the upper
right-hand corner to be taken to the full documentation for the time module.

    Catherine> Yes, certainly, in one place - but isn't it logical for the
    Catherine> docstring to be that one place?

I think most people would argue, "no".  Docstrings are helpers.  The library
reference manual is supposed to be comprehensive.

    Catherine> Here's where I would suggest drawing the line: if the method
    Catherine> is unusable without the information, and it's not easy to
    Catherine> guess or remember, and it's relatively concise, it should be
    Catherine> in the docstring.

This would be a pretty radical change to the documentation.  You're asking
that either

    * Docstrings become the comprehensive source of information instead of
      the library reference manual, or

    * A fair amount of information be duplicated between the library
      reference manual and the docstrings.

I suggest this discussion be moved to the doc-sig@python.org mailing list.
Those are the people who would be best equipped to discuss the overall
topic.  I'm just a single user with my personal perspective on the topic.
I'm not the guy who makes these decisions.

Skip
msg169193 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-08-27 10:20
I would like to add my +1 to this issue.  I suggest adding something like this:

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

Other codes may be available on your platform.  See documentation for the C library strftime function.
"""

This is a subjective selection in a subjective order of importance, so some bikesheding is welcome.  My choice was motivated by the assumption that most commonly used are the codes required to form RFC 3339 timestamps.  I deliberately omitted deprecated %y code and the %Z code that produces non-standardized TZ names.  I can be persuaded to add 12 hour clock codes.
msg169243 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-08-28 01:12
+1 on including am/pm-related codes. Blame us backwards, non-metric Americans. Sounds GTM otherwise.
msg171450 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2012-09-28 12:45
If we want to archive platform independence from the libc's strftime() and strptime() function and its bugs, we could include our own implementation. Or rather than writing our own code we may be able to include some working and well tested code.

BSD's libc contains the functions. Its license should allow the inclusion into Python core. http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libc/stdtime/

If you like my idea we should discuss it on python-ideas and start a new tracker entry.
msg171592 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-09-29 19:36
>If you like my idea we should discuss it on python-ideas and start a new tracker entry.

In the meantime I'd like to create a patch that incorporates Alexander's ideas. If any objections let me know.
msg171646 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-09-30 15:44
Changed docstring for timemodule.c to include format codes listed here: http://bugs.python.org/msg169193
msg171652 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-30 17:07
The patch contains non-ascii apostrophes: s/Locale’s/Locale's/
msg171660 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-09-30 19:04
Updated patch as per Ezio's comment.
msg171673 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-09-30 21:00
I'm going to bikeshed and again suggest that %I and %p be included for handling 12-hour clock times.

Also, the patch seems to only be for strftime(), and not strptime().
msg171676 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-09-30 21:44
New patch includes time.strptime and the additional changes suggested by Chris Rebert.
msg171683 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-09-30 23:14
This is now hardcore nitpicking, but I'm conflicted as to whether %p should be grouped with the other locale-related codes or with %I (since it's hard to imagine using %I or %p in a singleton capacity).

In any case, props to Mike for putting an actual patch together.
msg171836 - (view) Author: Roundup Robot (python-dev) Date: 2012-10-02 22:39
New changeset 3a0acdc25cca by Alexander Belopolsky in branch 'default':
Issue #9650: List commonly used format codes in time.strftime and time.strptime docsttings.
http://hg.python.org/cpython/rev/3a0acdc25cca
msg171838 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-02 23:49
Christian, did you ask on python-dev about your idea?
msg171840 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-10-03 00:03
Christian's or rather Skip's idea is covered by Issue 3173.  This was discussed several times on python-dev.
msg176764 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-12-01 22:01
Any reason to not backport this?
History
Date User Action Args
2012-12-01 22:01:28eric.araujosetmessages: + msg176764
2012-10-03 00:05:09brian.curtinsetnosy: - brian.curtin
2012-10-03 00:03:52belopolskysetmessages: + msg171840
2012-10-02 23:49:51eric.araujosetnosy: + eric.araujo
messages: + msg171838
2012-10-02 22:58:57belopolskysetstatus: open -> closed
stage: needs patch -> resolved
resolution: fixed
versions: + Python 3.4, - Python 3.3
2012-10-02 22:39:29python-devsetnosy: + python-dev
messages: + msg171836
2012-09-30 23:14:58cvrebertsetmessages: + msg171683
2012-09-30 21:44:27mikehoysetfiles: + issue9650-format-codes_v3.diff

messages: + msg171676
2012-09-30 21:00:11cvrebertsetmessages: + msg171673
2012-09-30 19:04:20mikehoysetfiles: + issue9650-format-codes_v2.diff

messages: + msg171660
2012-09-30 17:07:28ezio.melottisetnosy: + ezio.melotti
messages: + msg171652
2012-09-30 15:44:10mikehoysetfiles: + issue9650-format-codes.diff
keywords: + patch
messages: + msg171646
2012-09-29 19:36:30mikehoysetnosy: + mikehoy
messages: + msg171592
2012-09-28 12:45:26christian.heimessetnosy: + christian.heimes
messages: + msg171450
2012-08-28 01:12:16cvrebertsetmessages: + msg169243
2012-08-27 10:20:45belopolskysetassignee: docs@python -> belopolsky
messages: + msg169193
2012-08-27 09:03:30cvrebertsetnosy: + cvrebert
2011-04-15 21:23:34santoso.wijayasetassignee: docs@python
components: + Documentation, - Library (Lib)
versions: + Python 3.3, - Python 3.2
2011-03-19 19:10:36skip.montanarosetnosy: - skip.montanaro
2010-09-20 20:33:31eric.araujosetnosy: + docs@python
2010-08-30 14:42:54skip.montanarosetmessages: + msg115219
2010-08-30 13:49:38catherinesetmessages: + msg115215
2010-08-26 21:27:06skip.montanarosetmessages: + msg115028
2010-08-26 17:48:08catherinesetmessages: + msg115011
2010-08-20 18:02:58belopolskysetmessages: + msg114437
2010-08-20 18:01:16belopolskysetnosy: + belopolsky
messages: + msg114436
2010-08-20 17:10:47skip.montanarosetnosy: + skip.montanaro
messages: + msg114431
2010-08-20 16:24:10brian.curtinsetnosy: + brian.curtin
messages: + msg114428

keywords: + easy
stage: needs patch
2010-08-20 15:49:38catherinecreate