The docs for 'g' say "This prints the number as a fixed-point number,
unless the number is too large." Could you please explain what exactly
constitutes "too large"?

For 'g' formatting (either {} style or %-style) with precision p >= 1, I believe fixed-
point is used if and only if the formatted value satisfies

  1e-4 <= abs(formatted_value) < 10**precision.

Note that the 'formatted value' refers to the value rounded to p significant figures, 
not the original value of the number being formatted.  For example, in '%.6g' % 
9.999999e-5, the float rounded to 6 places is 1e-4, so the result is '0.0001', using 
fixed-point.  But '%.6g' % 9.999994e-5 gives '9.99999e-05'.

Mark's really the expert here, so I trust his description. Is his
description layman-speak enough for the docs?

That's amusing.  The moment I submitted the comment above I remember
thinking  'Hmm.  I could have explained that better.'

I'll try to come up with a doc patch.

Stealing the issue from Eric.

Benjamin, which docs are you looking at here?  The ones at:

http://docs.python.org/library/stdtypes.html#string-formatting-operations

say:

"""Floating point format. Uses lowercase exponential format if exponent is 
less than -4 or not less than precision, decimal format otherwise."""

which seem quite specific to me (though it could be made clearly exactly 
*what* exponent is meant here).

Ah.  Found them.

http://docs.python.org/library/string.html#formatspec

Proposed revision:

General format.  For a given precision ``p >= 1``, this rounds the number to ``p`` 
significant digits and then formats the result in either fixed-point format or in 
scientific notation, depending on its magnitude.  The precise rules are as follows: 
suppose that the result formatted with presentation type ``e`` and precision ``p-1`` 
would have exponent ``exp``.  Then if ``-4 <= exp < p``, the number is formatted as 
if with presentation type ``f`` and precision chosen in such a way as to give ``p`` 
significant digits.  Otherwise, the number is formatted as if with presentation type 
``e`` and precision ``p-1``.

A precision of ``0`` is treated as equivalent to a precision of ``1``.

That wording is okay with me. Maybe run it by Georg to see if he has any
suggestions? Or just check it in and see if anyone complains.

But I'm okay with it as-is.

Thanks for doing this.
Eric.

Thanks, Eric.  I noticed that the description was missing details of
what happens to trailing zeros (i.e., they're removed) and what happens
to special values:  infinities, zeros, nans.  Here's the revised revised 
text:

General format.  For a given precision ``p >= 1``, this rounds the
number to ``p`` significant digits and then formats the result in
either fixed-point format or in scientific notation, depending on its
magnitude.  The precise rules are as follows: suppose that the result
formatted with presentation type ``e`` and precision ``p-1`` would
have exponent ``exp``.  Then if ``-4 <= exp < p``, the number is
formatted as if with presentation type ``f`` and precision
``p-1-exp``.  Otherwise, the number is formatted as if with
presentation type ``e`` and precision ``p-1``.  In both cases trailing
zeros are removed from the significand, as is the decimal point if
there are no remaining digits following it.

Postive and negative infinity, positive and negative zero, and nans,
are formatted as ``inf``, ``-inf``, ``0``, ``-0`` and ``nan``
respectively.

A precision of ``0`` is treated as equivalent to a precision of ``1``.

I obviously hadn't thought of those cases, either. This version looks
good(er) to me.

The "as if with" feels strange, otherwise it is fine with me.

Okay.  I'll replace the 'as if with' with simply 'with'.  That doesn't 
quite meet my favoured level of pedantry any more, but it does read better 
and it's not going to lead to any confusion.  :)

I think the 'as if with' is probably valid English, but if you want to
make it sound better yet retain the same level of pedantry you could
instead say, e.g.: "in the same way as presentation type e using
precision p-1".

Thanks Georg and Eric for the feedback!  New wording committed in
r75289 (trunk), r75290 (py3k), r75291 (release31-maint).  Leaving open 
for the backport to release26-maint.

BTW, it's much easier to describe the rules in Python than in prose:

def strip_zero_dot(sig):
    return sig.rstrip('0').rstrip('.') if '.' in sig else sig

def gformat(x, p=6):
    if math.isinf(x) or math.isnan(x) or not x:
        return '{:.0f}'.format(x)
    p = max(p, 1)
    sig, exp = '{:.{}e}'.format(x, p-1).split('e')
    if -4 <= int(exp) < p:
        return strip_zero_dot('{:.{}f}'.format(x, p-1-int(exp)))
    else:
        return strip_zero_dot(sig) + 'e' + exp

Looks like this was merged to release26-maint by Georg in r75790.  Thanks, 
Georg!