Clarify 0 prefix for width specifier in str.format doc,

[py-user]

BPO	15660
Nosy	@terryjreedy, @ericvsmith, @ezio-melotti, @py-user

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2016-03-21.01:06:59.065>
created_at = <Date 2012-08-15.04:20:39.515>
labels = ['type-bug', 'docs']
title = 'Clarify 0 prefix for width specifier in str.format doc,'
updated_at = <Date 2016-08-16.04:36:43.232>
user = 'https://github.com/py-user'

bugs.python.org fields:

activity = <Date 2016-08-16.04:36:43.232>
actor = 'bignose'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2016-03-21.01:06:59.065>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2012-08-15.04:20:39.515>
creator = 'py.user'
dependencies = []
files = []
hgrepos = []
issue_num = 15660
keywords = []
message_count = 11.0
messages = ['168258', '168259', '168468', '168471', '261859', '261861', '261881', '262097', '262098', '262187', '272828']
nosy_count = 7.0
nosy_names = ['terry.reedy', 'eric.smith', 'ezio.melotti', 'docs@python', 'py.user', 'bignose', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue15660'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[py-user]

>>> '{: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 '>'

[py-user]

found a small string in the doc about zero padding, which enables alignment equal to =

[terryjreedy]

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.

[python-dev]

New changeset 85cd54b2d3a1 by Terry Jan Reedy in branch '2.7':
bpo-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':
bpo-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 bpo-15660
http://hg.python.org/cpython/rev/f181dd088e63

[terryjreedy]

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.