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