Documenting that would help get people using datetime objects with string.format more.

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

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.

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.

This documentation should also be added for datetime.time and datetime.date, in addition to datetime.datetime.

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.

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.

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

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?

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.

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.