New submission from Hugo Prod'homme:
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 :
http://strftime.org/";>http://strftime.org/
Some idea was provided to add this indications in the python docs.
http://bugs.python.org/issue9650";>http://bugs.python.org/issue9650
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 :
https://docs.python.org/2/library/string.html";>https://docs.python.org/2/library/string.html
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.
--
files: format_docstring_v0.1.txt
messages: 287539
nosy: hugo.prodho...@gmx.fr
priority: normal
severity: normal
status: open
title: Documenting format() function
type: enhancement
versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7
Added file: http://bugs.python.org/file46625/format_docstring_v0.1.txt
___
Python tracker
<http://bugs.python.org/issue29526>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
