classification
Title: Clarify 0 prefix for width specifier in str.format doc,
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: bignose, docs@python, eric.smith, ezio.melotti, py.user, python-dev, terry.reedy
Priority: normal Keywords:

Created on 2012-08-15 04:20 by py.user, last changed 2016-08-16 04:36 by bignose. This issue is now closed.

Messages (11)
msg168258 - (view) Author: py.user (py.user) * Date: 2012-08-15 04:20
>>> '{:02}'.format('a')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: '=' alignment not allowed in string format specifier
>>>


according to http://docs.python.org/py3k/library/string.html#formatspec
the default alignment is '<' or '>'
msg168259 - (view) Author: py.user (py.user) * Date: 2012-08-15 04:27
found a small string in the doc about zero padding, which enables alignment equal to =
msg168468 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-08-17 19:13
As I read the docs, the error message is correct and this issue is invalid as a behavior issue. I read the OP's second message as more or less saying this also.

"'=' 	Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form ‘+000000120’. This alignment option is only valid for numeric types."

"If the width field is preceded by a zero ('0') character, this enables zero-padding. This is equivalent to an alignment type of '=' and a fill character of '0'."

So ":02" is equivalent to ":0=2", which is invalid.

>>> '{:02d}'.format(1)
'01'
works fine.

I decided make this a doc issue and add " for numeric types" after "this enables zero-padding" before closing this.
msg168471 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-17 19:42
New changeset 85cd54b2d3a1 by Terry Jan Reedy in branch '2.7':
Issue 15660: Clarify 0 prefix for width field in str.format doc.
http://hg.python.org/cpython/rev/85cd54b2d3a1

New changeset 6bc14974024f by Terry Jan Reedy in branch '3.2':
Issue 15660: Clarify 0 prefix for width field in str.format doc.
http://hg.python.org/cpython/rev/6bc14974024f

New changeset f181dd088e63 by Terry Jan Reedy in branch 'default':
Merge with 3.2 #15660
http://hg.python.org/cpython/rev/f181dd088e63
msg261859 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-03-16 20:56
This came up again on python-list today in thread "Replace weird error message?" by "the.gerenuk--- via Python-list".  After reading the discussion, I decided that expecting someone to read and connect together two sentences half a page apart is expecting a bit too much.

'''
'=' 	Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form ‘+000000120’. This alignment option is only valid for numeric types.
'''

Add "It becomes the default when '0' precedes the field width."

''' 
Preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types. This is equivalent to a fill character of '0' with an alignment type of '='.
'''

This is not true when an explicit alignment other than '=' is given.
>>> "{:09}".format(-1)
'-00000001'
>>> "{:>09}".format(-1)  # 2.7.11 and 3.5.1
'0000000-1'

Proposal: Replace with
'''
When no explicit alignment is given, preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types. This is equivalent to a fill character of '0' with an alignment type of '='.
'''

I presume the problem with changing the error message is that it is not immediately known that alignment was set implicitly, by 0 before decimal width, rather than explicitly.  If the spec string is still available, it could be searched and the message adjusted if '=' is not present.  That proposal should be a new issue if someone wants to push it.
msg261861 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2016-03-16 21:03
> '''
> When no explicit alignment is given, preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types. This is equivalent to a fill character of '0' with an alignment type of '='.
> '''

I think that's good.

> I presume the problem with changing the error message is that it is not immediately known that alignment was set implicitly, by 0 before decimal width, rather than explicitly.  If the spec string is still available, it could be searched and the message adjusted if '=' is not present.  That proposal should be a new issue if someone wants to push it.

Yes, that's the problem. I guess it would be easier to keep track of
which fields were set via defaults, and which explicitly. Currently,
that information is lost.
msg261881 - (view) Author: py.user (py.user) * Date: 2016-03-17 02:38
There is a funny thing in 3.6.0a0

>>> '{:<09}'.format(1)
'100000000'
>>> '{:<09}'.format(10)
'100000000'
>>> '{:<09}'.format(100)
'100000000'
>>>

Actually, it behaves like a string, but the format should call internal format function of the passed number and the internal format function should not format different numbers as equal numbers.

Why does it represent number 1 as number 10?

>>> format(1, '<02')
'10'
>>> format(10, '')
'10'
>>>

I guess, there should be a restriction.
Zero padding for numbers should be correct.
msg262097 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-03-21 01:03
You example says to left justify '1'
>>> format(1, '<2')
'1 '
and then pad with '0' instead of ' '.
msg262098 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-03-21 01:06
New changeset de669512df97 by Terry Jan Reedy in branch '2.7':
Issue #15660: Further clarify 0 prefix for width specifier in formats.
https://hg.python.org/cpython/rev/de669512df97

New changeset 34cbc5d8a173 by Terry Jan Reedy in branch '3.5':
Issue #15660: Further clarify 0 prefix for width specifier in formats.
https://hg.python.org/cpython/rev/34cbc5d8a173
msg262187 - (view) Author: py.user (py.user) * Date: 2016-03-22 14:50
Terry J. Reedy (terry.reedy) wrote:
> You example says to left justify '1'

Nope.

The fill character goes before alignment in the specification (grammatics).

>>> format(1, '0<2')
'10'
>>>

This is right. But 02 - is zero padding of a number which can be done only from the left side.

'<02' means "justify to the left zero padded number"
msg272828 - (view) Author: Ben Finney (bignose) Date: 2016-08-16 04:36
Terry Reedy wrote:

> If the spec string is still available, it could be searched and the message adjusted if '=' is not present.  That proposal should be a new issue if someone wants to push it.

Done now, see Issue 27772.
History
Date User Action Args
2016-08-16 04:36:43bignosesetnosy: + bignose
messages: + msg272828
2016-03-22 14:50:16py.usersetmessages: + msg262187
2016-03-21 01:06:59terry.reedysetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2016-03-21 01:06:33python-devsetmessages: + msg262098
2016-03-21 01:03:04terry.reedysetmessages: + msg262097
2016-03-17 02:38:34py.usersetmessages: + msg261881
2016-03-16 21:03:02eric.smithsetmessages: + msg261861
2016-03-16 20:56:02terry.reedysetstatus: closed -> open
versions: + Python 3.5, Python 3.6, - Python 3.2, Python 3.3
messages: + msg261859

resolution: fixed -> (no value)
stage: resolved -> patch review
2012-08-17 19:45:05terry.reedysetassignee: docs@python -> terry.reedy
2012-08-17 19:44:32terry.reedysetstatus: open -> closed
title: In str.format there is a misleading error message about alignment -> Clarify 0 prefix for width specifier in str.format doc,
stage: needs patch -> resolved
2012-08-17 19:43:49terry.reedysetresolution: fixed
2012-08-17 19:42:51python-devsetnosy: + python-dev
messages: + msg168471
2012-08-17 19:13:31terry.reedysetversions: + Python 2.7, Python 3.3
nosy: + terry.reedy, docs@python

messages: + msg168468

assignee: docs@python
components: + Documentation, - Interpreter Core
2012-08-15 04:27:56py.usersetmessages: + msg168259
versions: - Python 2.7, Python 3.3, Python 3.4
2012-08-15 04:22:52ezio.melottisetnosy: + eric.smith, ezio.melotti
stage: needs patch

versions: + Python 2.7, Python 3.3, Python 3.4
2012-08-15 04:20:39py.usercreate