Documenting format() function

[goyou]

BPO	29526
Nosy	@terryjreedy, @ncoghlan, @ericvsmith, @bitdancer, @serhiy-storchaka, @marco-buttu, @goYou, @iritkatriel
PRs	bpo-29526 Add reference to help('FORMATTING') in format() builtin #166 [3.6] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). #3491 [2.7] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). #3492
Files	format_docstring_v0.1.txt

^{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 = None
closed_at = <Date 2020-09-20.12:53:03.550>
created_at = <Date 2017-02-10.14:13:56.072>
labels = ['type-feature', '3.7']
title = 'Documenting format() function'
updated_at = <Date 2020-09-20.12:53:03.550>
user = 'https://github.com/goyou'

bugs.python.org fields:

activity = <Date 2020-09-20.12:53:03.550>
actor = 'eric.smith'
assignee = 'none'
closed = True
closed_date = <Date 2020-09-20.12:53:03.550>
closer = 'eric.smith'
components = []
creation = <Date 2017-02-10.14:13:56.072>
creator = 'hugo.prodhomme@gmx.fr'
dependencies = []
files = ['46625']
hgrepos = []
issue_num = 29526
keywords = ['patch']
message_count = 11.0
messages = ['287539', '287542', '287544', '287547', '287548', '287549', '287550', '287570', '301860', '301861', '377216']
nosy_count = 8.0
nosy_names = ['terry.reedy', 'ncoghlan', 'eric.smith', 'r.david.murray', 'serhiy.storchaka', 'marco.buttu', 'hugo.prodhomme@gmx.fr', 'iritkatriel']
pr_nums = ['166', '3491', '3492']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29526'
versions = ['Python 2.7', 'Python 3.6', 'Python 3.7']

[goyou]

Hello python contributors,
this is my first time on python.org and I am coming with a suggestion.

The idea is to help people that have to format strings containing numbers of various kinds, I am from the scientific domain but this should help everybody anyway.

In the past the strftime was the best way to format numbers in strings (truncating to some digits after point, setting to exponent notation, etc...). To remind the "strf language" one had to use the internet or a document such as this page :
<a href="http://strftime.org/"\>http://strftime.org/\</a>

Some idea was provided to add this indications in the python docs.
<a href="http://bugs.python.org/issue9650"\>http://bugs.python.org/issue9650\</a>

Now the format() function has appeared in the python __builtins__ and this is even more adequate to add help about the string formatting, because we can write the "Format Specification Mini-Language" directly inside the docstring of the format.__doc__ . See the paragraph named "7.1.3.1. Format Specification Mini-Language" in the following page :
<a href="https://docs.python.org/2/library/string.html"\>https://docs.python.org/2/library/string.html\</a>

I emphasize, the interest of this is to allow the user to be reminded of the formatting options without opening another document than his(her) script, to avoid breaking the workflow.

I am providing what I think is the minimal material that the docstring should contains within the attached file. I am not really familiar with docstring formatting according to PEP (436?) and someone should help getting this in the right way of writing. Furthermore, a specific syntax is needed within the string in addition to the format() arguments, this should be described. And the reminder about the mini-language should appear clearly as a reminder. These are two supplemental difficulties in comparison with an usual docstring.

To anyone thinking something else should be added to the docstring; please add or say it.

PS: I think I can start from the matplotlib.pyplot.plot.__doc__ as a template to complete the format.__doc__ but I have some work aside for now.

[ericvsmith]

Since these codes don't apply to all types, you'll need some words saying what they do apply to. For example, None being the same as "g" is true for int, float, and Decimal; but None is "s" for strings.

And, for example, none of the listed codes apply to datetime's.

I'm +0 on this if we can get the wording right.

[bitdancer]

Thanks for wanting to help improve python.

I'm not entirely clear on what you are proposing. I *think* you want to add something to the 'format' docstring? As Eric mentioned the 'mini language' depends on the datatype, so it is going to be hard to cram accurate information into a docstring, where the full context of the documentation explanation of how format interacts with data types is missing. We try to keep docstrings as short reminders. In that regard, the format docstring *is* perhaps a bit lacking :) A reminder of the BNF of the minilanguage would also be helpful if we could cram that in somehow. It may just be too complex a topic for a docstring, though.

I'm also not clear why you are referring to strftime and numbers in the same sentence. strftime is for date formatting. I certainly don't think it is appropriate to try to jam that complex subtopic into the format docstring :) Maybe you meant 'printf', which % formatting followed fairly closely?

[serhiy-storchaka]

I think it would be worth to extend docstrings of __format__ methods of concrete types for including the description of type-specific format specifiers. But the docstring of format() shouldn't contain the description of format specifiers of all builtin types.

Detailed documentation of format specification mini-language with tables and examples you can get by requesting the help for FORMATTING. "help('FORMATTING')" or "pydoc3 FORMATTING". It may be worth to add a reference to FORMATTING from the format() docstring.

[marco-buttu]

It may be worth to add a reference to FORMATTING from the
format() docstring.

+1 :-)

[bitdancer]

Serhiy: those are both great ideas. +1 from me too. Then we can even have the date formatting documented without cluttering up the main docstring, if we wish :) The format docstring should then also mention doing help on the __format__ method of concrete types.

[goyou]

+1 :
Adding the reference to help('FORMATTING') will indeed solve all the problems I was thinking about at first.

--

I realized I was thinking only about a small part of the problem thanks to your answers. I wasn't even thinking about the dates and other types... So I agree applying my first idea will be a big mess.

(... and yes I was referring to printf formatting)

[terryjreedy]

+1 of Serhiy's ideas. I was not aware that FORMATTING had been added. And this could be specifically helpful.

>>> help(int.__format__)
Help on method_descriptor:

__format__(...)
    default object formatter

[serhiy-storchaka]

New changeset c67838d by Serhiy Storchaka in branch '3.6':
[3.6] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). (bpo-3491)
c67838d

[serhiy-storchaka]

New changeset 6ed7aff by Serhiy Storchaka in branch '2.7':
[2.7] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). (bpo-3492)
6ed7aff

[iritkatriel]

It looks like this is complete and can be closed.