[issue9650] format codes in time.strptime docstrings
Éric Araujo added the comment: Any reason to not backport this? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Roundup Robot added the comment: 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 -- nosy: +python-dev ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Alexander Belopolsky alexander.belopol...@gmail.com: -- resolution: - fixed stage: needs patch - committed/rejected status: open - closed versions: +Python 3.4 -Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Éric Araujo added the comment: Christian, did you ask on python-dev about your idea? -- nosy: +eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Alexander Belopolsky added the comment: Christian's or rather Skip's idea is covered by Issue 3173. This was discussed several times on python-dev. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Brian Curtin br...@python.org: -- nosy: -brian.curtin ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Mike Hoy added the comment: Changed docstring for timemodule.c to include format codes listed here: http://bugs.python.org/msg169193 -- keywords: +patch Added file: http://bugs.python.org/file27358/issue9650-format-codes.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Ezio Melotti added the comment: The patch contains non-ascii apostrophes: s/Locale’s/Locale's/ -- nosy: +ezio.melotti ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Mike Hoy added the comment: Updated patch as per Ezio's comment. -- Added file: http://bugs.python.org/file27364/issue9650-format-codes_v2.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Chris Rebert added the 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(). -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Mike Hoy added the comment: New patch includes time.strptime and the additional changes suggested by Chris Rebert. -- Added file: http://bugs.python.org/file27365/issue9650-format-codes_v3.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Chris Rebert added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Mike Hoy added the comment: 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. -- nosy: +mikehoy ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Christian Heimes added the comment: 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. -- nosy: +christian.heimes ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Chris Rebert pyb...@rebertia.com: -- nosy: +cvrebert ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Alexander Belopolsky added the comment: 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. -- assignee: docs@python - belopolsky ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Chris Rebert added the comment: +1 on including am/pm-related codes. Blame us backwards, non-metric Americans. Sounds GTM otherwise. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Santoso Wijaya santoso.wij...@gmail.com: -- assignee: - docs@python components: +Documentation -Library (Lib) versions: +Python 3.3 -Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Skip Montanaro s...@pobox.com: -- nosy: -skip.montanaro ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Changes by Éric Araujo mer...@netwok.org: -- nosy: +d...@python ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Catherine Devlin fredv8vi...@liquidid.net added the comment: 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? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Skip Montanaro s...@pobox.com added the comment: 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-...@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 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Catherine Devlin fredv8vi...@liquidid.net added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Skip Montanaro s...@pobox.com added the comment: 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 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
New submission from Catherine Devlin fredv8vi...@liquidid.net: 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. -- components: Library (Lib) messages: 114427 nosy: catherine priority: normal severity: normal status: open title: format codes in time.strptime docstrings type: feature request versions: Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Brian Curtin cur...@acm.org added the comment: +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 :) -- keywords: +easy nosy: +brian.curtin stage: - needs patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Skip Montanaro s...@pobox.com added the comment: 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. -- nosy: +skip.montanaro ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: 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. -- nosy: +belopolsky ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9650] format codes in time.strptime docstrings
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: 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. :-) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9650 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
