[issue29526] Documenting format() function

[Eric V. Smith]

Change by Eric V. Smith :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Irit Katriel]

Irit Katriel  added the comment:

It looks like this is complete and can be closed.

--
nosy: +iritkatriel

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Serhiy Storchaka added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Serhiy Storchaka added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
versions: +Python 2.7 -Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
pull_requests: +3485

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
keywords: +patch
pull_requests: +3484
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Nick Coghlan]

Changes by Nick Coghlan :


--
nosy: +ncoghlan

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Amit Kumar]

Changes by Amit Kumar :


--
pull_requests: +130

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Terry J. Reedy]

Terry J. Reedy added the comment:

+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

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Hugo Prod'homme]

Hugo Prod'homme added the comment:

+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)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[R. David Murray]

R. David Murray added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Marco Buttu]

Marco Buttu added the comment:

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

+1 :-)

--
nosy: +marco.buttu

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

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.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[R. David Murray]

R. David Murray added the comment:

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?

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Eric V. Smith]

Eric V. Smith added the comment:

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.

--
nosy: +eric.smith
versions:  -Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29526] Documenting format() function

[Hugo Prod'homme]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com