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.

+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 :)

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.

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

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

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

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

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

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

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.

+1 on including am/pm-related codes. Blame us backwards, non-metric Americans. Sounds GTM otherwise.

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.

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

Changed docstring for timemodule.c to include format codes listed here: http://bugs.python.org/msg169193

The patch contains non-ascii apostrophes: s/Locale’s/Locale's/

Updated patch as per Ezio's comment.

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

New patch includes time.strptime and the additional changes suggested by Chris Rebert.

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.

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

Christian, did you ask on python-dev about your idea?

Christian's or rather Skip's idea is covered by Issue 3173.  This was discussed several times on python-dev.

Any reason to not backport this?