[New-bugs-announce] [issue24417] Type-specific documentation for __format__ methods

[Skip Montanaro]

New submission from Skip Montanaro:

I am only now just prying my fingers off printf-style string
formatting. The new syntax always seemed Perl-like to me, so I ignored
it. Finally, yesterday, I got some cheat sheet pointers from
comp.lang.python and dove in.

I hit a minor roadblock when I couldn't find any type-specific
documentation for the various __format__ methods. In the documentation
on the format() builtin
(https://docs.python.org/3.5/library/functions.html#format) I read,
"The interpretation of format_spec will depend on the type of the
value argument..." which led me to believe I would find something
about (for example) float.__format__ in the section on floats
(https://docs.python.org/3.5/library/stdtypes.html#typesnumeric).

I realize now that the documentation for many formats is in the string
documentation
(https://docs.python.org/3.5/library/string.html#formatspec), but I
think it would still be useful to have at least stubs in the
documentation for the __format__ method of the various builtin types,
even if all those stubs to is refer the reader to the string
documentation.

I started to work on a patch, but I quickly got myself confused about
where to describe <sometype>.__format__. Perhaps it's time that
stdtypes.rst is broken into multiple files, with the structure of the
documentation for the various builtin types made more uniform. For
instance, int and float have sections describing methods, while list,
tuple, set, and dict don't.

----------
assignee: docs at python
components: Documentation
messages: 245063
nosy: docs at python, skip.montanaro
priority: normal
severity: normal
status: open
title: Type-specific documentation for __format__ methods

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24417>
_______________________________________