classification
Title: Documenting format() function
Type: enhancement Stage: resolved
Components: Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: eric.smith, hugo.prodhomme@gmx.fr, iritkatriel, marco.buttu, ncoghlan, r.david.murray, serhiy.storchaka, terry.reedy
Priority: normal Keywords: patch

Created on 2017-02-10 14:13 by hugo.prodhomme@gmx.fr, last changed 2020-09-20 12:53 by eric.smith. This issue is now closed.

Files
File name Uploaded Description Edit
format_docstring_v0.1.txt hugo.prodhomme@gmx.fr, 2017-02-10 14:13
Pull Requests
URL Status Linked Edit
PR 166 merged aktech, 2017-02-19 06:21
PR 3491 merged serhiy.storchaka, 2017-09-11 05:55
PR 3492 merged serhiy.storchaka, 2017-09-11 06:04
Messages (11)
msg287539 - (view) Author: Hugo Prod'homme (hugo.prodhomme@gmx.fr) Date: 2017-02-10 14:13
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.
msg287542 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2017-02-10 14:46
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.
msg287544 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-02-10 14:59
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?
msg287547 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-02-10 15:19
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.
msg287548 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-02-10 15:24
> It may be worth to add a reference to FORMATTING from the
> format() docstring.

+1 :-)
msg287549 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-02-10 15:34
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.
msg287550 - (view) Author: Hugo Prod'homme (hugo.prodhomme@gmx.fr) Date: 2017-02-10 15:43
+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)
msg287570 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-02-10 20:41
+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
msg301860 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-09-11 06:26
New changeset c67838da2cde6fa3f1bef11f08719237983e6990 by Serhiy Storchaka in branch '3.6':
[3.6] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). (#3491)
https://github.com/python/cpython/commit/c67838da2cde6fa3f1bef11f08719237983e6990
msg301861 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-09-11 06:26
New changeset 6ed7aff8948e50708f048f3f7fd41809259d1777 by Serhiy Storchaka in branch '2.7':
[2.7] bpo-29526: Add reference to help('FORMATTING') in format() builtin (GH-166). (#3492)
https://github.com/python/cpython/commit/6ed7aff8948e50708f048f3f7fd41809259d1777
msg377216 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2020-09-20 12:22
It looks like this is complete and can be closed.
History
Date User Action Args
2020-09-20 12:53:03eric.smithsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-09-20 12:22:17iritkatrielsetnosy: + iritkatriel
messages: + msg377216
2017-09-11 06:26:41serhiy.storchakasetmessages: + msg301861
2017-09-11 06:26:18serhiy.storchakasetmessages: + msg301860
2017-09-11 06:25:19serhiy.storchakasetversions: + Python 2.7, - Python 3.5
2017-09-11 06:04:39serhiy.storchakasetpull_requests: + pull_request3485
2017-09-11 05:55:25serhiy.storchakasetkeywords: + patch
stage: patch review
pull_requests: + pull_request3484
2017-05-27 05:28:21ncoghlansetnosy: + ncoghlan
2017-02-19 06:21:48aktechsetpull_requests: + pull_request130
2017-02-10 20:41:38terry.reedysetnosy: + terry.reedy
messages: + msg287570
2017-02-10 15:43:55hugo.prodhomme@gmx.frsetmessages: + msg287550
2017-02-10 15:34:02r.david.murraysetmessages: + msg287549
2017-02-10 15:24:07marco.buttusetnosy: + marco.buttu
messages: + msg287548
2017-02-10 15:19:58serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg287547
2017-02-10 14:59:35r.david.murraysetnosy: + r.david.murray
messages: + msg287544
2017-02-10 14:46:03eric.smithsetnosy: + eric.smith

messages: + msg287542
versions: - Python 3.3, Python 3.4
2017-02-10 14:13:56hugo.prodhomme@gmx.frcreate