classification
Title: Document that datetime.__format__ is datetime.strftime
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: BreamoreBoy, asvetlov, belopolsky, brett.cannon, docs@python, eric.araujo, eric.smith, ezio.melotti, flox, heikki.partanen, python-dev, r.david.murray
Priority: low Keywords: easy, patch

Created on 2010-06-06 03:26 by brett.cannon, last changed 2013-04-04 06:19 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue8913.patch heikki.partanen, 2012-10-23 13:23 review
issue8913-2.patch heikki.partanen, 2012-10-29 19:51 review
issue8913-3.patch heikki.partanen, 2012-10-30 05:34 review
issue8913-4.patch heikki.partanen, 2013-04-03 08:15 review
issue8913-5.patch heikki.partanen, 2013-04-04 05:05 review
Messages (25)
msg107179 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2010-06-06 03:26
Documenting that would help get people using datetime objects with string.format more.
msg107184 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-06 05:56
I wonder if this is subject to change.  I find it odd that

>>> "{:g}".format(1e3)
'1000'

but one has to use % in

>>> "{:%Y}".format(datetime.now())
'2010'

It is also different from PEP 3101 recommendation:
"""
    An example is the 'datetime' class,
    whose format specifiers might look something like the
    arguments to the strftime() function:

        "Today is: {0:a b d H:M:S Y}".format(datetime.now())
"""
The above, however, should probably be

"Today is: {0:a} {0:b} {0:d} {0:H}:{0:M}:{0:S} {0:Y}".format(datetime.now())
msg107211 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2010-06-06 19:15
I don't find it odd at all that you use datetime-specific formats instead of integral formats to get numbers out of a datetime object; they are totally different things. And one of the reasons for __format__ support is to have DSLs such as the one for datetime objects.

As for pulling out individual objects, that just looks ugly, so I wouldn't advocate pulling out individual values and then formatting them individually in the string itself.
msg107222 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2010-06-06 20:17
I think Alexander's example is best written as:
"Today is: {0:%a %b %d %H:%M:%S %Y}".format(datetime.now())

I agree with Brett that there's nothing unusual about having type-specific formatting languages, and for datetime strftime is the obvious choice. It's a little unfortunate that % is used, as it's mildly confusing with %-formatting, but not much can be done with that issue.
msg107223 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2010-06-06 20:19
This documentation should also be added for datetime.time and datetime.date, in addition to datetime.datetime.
msg107228 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-06-06 21:06
The problem I have with strftime %-format codes is that according to BSD manual page they have already ran out of English alphabet and still "there is no conversion specification for the phase of the moon." :-)

On a serious note, there are no codes to format TZ offset hours and minutes separately which precludes specifying an important RFC 3339 format.

I think we should take this opportunity to define a comprehensive mini-language for datetime formatting rather than slavishly reuse strftime.

The new mini-language may end up to be a superset of that for strftime, but I would rather not commit to supporting %-codes indefinitely.
msg107233 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2010-06-06 21:29
Unfortunately I think it's too late to do anything about this. I, for one, have many lines of code in production that use the strftime format specifier for datetime.__format__.

You only option would be to invent a new language that was somehow distinguishable from the strftime specifiers, but I doubt you'd get much support.

I think it's better to extend strftime, and let __format__ benefit from it.
msg107236 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-06 21:42
I think this particular wheel has one very good reinvention as the Locale Data Markup Language specification. Example from the Python Babel package:

>>> format_datetime(dt, "yyyyy.MMMM.dd GGG hh:mm a", locale='en')
u'02007.April.01 AD 03:30 PM'

http://unicode.org/reports/tr35/#Date_Format_Patterns
http://babel.edgewall.org/wiki/Documentation/dates.html#pattern-syntax
msg117953 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-10-04 14:49
Alexander closed issue 7789 in favor of this one, which is fine, but I want to respond to Eric's rejection there of including info about datetime in the 'format mini language' section of the docs.  His point was that only the builtin types were documented there, but if the goal is to get people to actually use this facility, it would be helpful if some mention were made there of other stdlib types that support __format__.  Some set of 'see also' links, perhaps in a footnote?
msg117954 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2010-10-04 14:57
I'm okay with that. Grepping Lib shows that date/datetime/time and Decimal are the only types that implement __format__. Decimal largely implements the same language as float.
msg151388 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-16 16:39
IMO, now that two official releases of Python 3 have shipped with this behavior (3.1 and 3.2), it is too late to think about changing what datetime.__format__ does, and we should merely document that it is the same as strftime.
msg173614 - (view) Author: Heikki Partanen (heikki.partanen) * Date: 2012-10-23 13:23
Added documentation for __format__ for datetime, time and date, and also added example code for using string.format. Seemed to merge cleanly to 3.4 and 2.7.
msg173651 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-24 01:10
Thanks!  Reviewed.
msg174149 - (view) Author: Heikki Partanen (heikki.partanen) * Date: 2012-10-29 19:51
Thanks for the comments, Eric!

I reworded the docs and improved the examples too (being stuck in 2.6 I didn't even know about the cool autonumbering :)
msg174181 - (view) Author: Heikki Partanen (heikki.partanen) * Date: 2012-10-30 05:34
Grammar fixed
msg174902 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2012-11-05 12:37
To Heikki Partanen excellent point in the review about date __format__ strings allowing you to combine date formatting with other types of formatting:

This is a great point. It's the lack of this that (for example) requires the logging module to have a separate datefmt parameter. With %-formatting, there's no easy way to say:

'{timestamp:%Y%m%d-%H%M%S} {hostname:^40} {count:02d}'.format(timestamp=ts, hostname=host, count=count)

That is, with %-formatting you can't have a single string that specifies both a date/time format and other formatting as well as other formatting specifiers.

I don't think the example in the patch is great, but I do think that it's a good point that needs to be emphasized.
msg185788 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2013-04-02 01:43
Can issue8913-3.patch be committed or are any further tweaks needed?
msg185875 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-04-03 01:29
Ezio, you are the latest reviewer, do you have outstanding comments?
msg185894 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2013-04-03 06:46
My only suggestion would be that the datetime example would be better if it actually used a time portion, similar to the strftime example above it. Otherwise, it looks good.
msg185897 - (view) Author: Heikki Partanen (heikki.partanen) * Date: 2013-04-03 08:15
Improved the datetime example to have time part
msg185914 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2013-04-03 10:47
That looks great. Thanks!
msg185990 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-04 01:04
I left another review with a couple of suggestions.
The patch is OK, it's just that the examples look a bit meaningless to me.
msg186001 - (view) Author: Heikki Partanen (heikki.partanen) * Date: 2013-04-04 05:05
The examples in the previous patches were trying to show some "real-worldish" use cases, but I admit that they don't fit in that well to the existing examples shown in the docs.

The new examples Ezio suggested are more straightforward and better in line with existing docs, so uploaded a new patch with updated examples.
msg186005 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-04-04 06:18
New changeset 40f582a73901 by Ezio Melotti in branch '3.3':
#8913: add examples and docs for date/time/datetime.__format__.  Patch by Heikki Partanen.
http://hg.python.org/cpython/rev/40f582a73901

New changeset 8dd7f7134700 by Ezio Melotti in branch 'default':
#8913: merge with 3.3.
http://hg.python.org/cpython/rev/8dd7f7134700

New changeset 0dac103a41bb by Ezio Melotti in branch '2.7':
#8913: add examples and docs for date/time/datetime.__format__.  Patch by Heikki Partanen.
http://hg.python.org/cpython/rev/0dac103a41bb
msg186006 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-04 06:19
Fixed, thanks for the patch!
History
Date User Action Args
2013-04-04 06:19:16ezio.melottisetstatus: open -> closed
type: behavior -> enhancement
messages: + msg186006

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: patch review -> resolved
2013-04-04 06:18:38python-devsetnosy: + python-dev
messages: + msg186005
2013-04-04 05:05:36heikki.partanensetfiles: + issue8913-5.patch

messages: + msg186001
2013-04-04 01:04:12ezio.melottisetstage: patch review
messages: + msg185990
versions: + Python 3.4, - Python 3.2
2013-04-03 10:47:03eric.smithsetmessages: + msg185914
2013-04-03 08:15:45heikki.partanensetfiles: + issue8913-4.patch

messages: + msg185897
2013-04-03 06:46:48eric.smithsetmessages: + msg185894
2013-04-03 01:29:53eric.araujosetmessages: + msg185875
2013-04-02 01:43:07BreamoreBoysetnosy: + BreamoreBoy
messages: + msg185788
2012-11-05 12:37:30eric.smithsetmessages: + msg174902
2012-10-30 05:34:59heikki.partanensetfiles: + issue8913-3.patch

messages: + msg174181
2012-10-29 19:51:42heikki.partanensetfiles: + issue8913-2.patch

messages: + msg174149
2012-10-24 21:26:24ezio.melottisetnosy: + ezio.melotti
2012-10-24 13:44:40asvetlovsetnosy: + asvetlov
2012-10-24 01:10:26eric.araujosetmessages: + msg173651
2012-10-23 13:23:22heikki.partanensetfiles: + issue8913.patch

nosy: + heikki.partanen
messages: + msg173614

keywords: + patch
2012-01-16 16:39:36eric.araujosetmessages: + msg151388
2011-11-16 16:45:41floxsettype: behavior
versions: + Python 3.3, - Python 2.6, Python 3.1
2010-10-04 14:57:03eric.smithsetmessages: + msg117954
2010-10-04 14:49:46r.david.murraysetnosy: + r.david.murray
messages: + msg117953
2010-10-04 14:14:57belopolskylinkissue7789 superseder
2010-09-09 19:13:34floxsetnosy: + flox
2010-06-06 21:42:33eric.araujosetnosy: + eric.araujo
messages: + msg107236
2010-06-06 21:29:44eric.smithsetmessages: + msg107233
versions: + Python 2.6, Python 3.1, Python 2.7
2010-06-06 21:06:17belopolskysetmessages: + msg107228
2010-06-06 20:19:02eric.smithsetmessages: + msg107223
2010-06-06 20:18:00eric.smithsetnosy: + eric.smith
messages: + msg107222
2010-06-06 19:15:18brett.cannonsetmessages: + msg107211
2010-06-06 05:56:11belopolskysetnosy: + belopolsky
messages: + msg107184
2010-06-06 03:26:18brett.cannoncreate