Type-specific documentation for __format__ methods

[smontanaro]

BPO	24417
Nosy	@smontanaro, @ericvsmith, @csabella

^{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: ```python assignee = None closed_at = None created_at = labels = ['docs'] title = 'Type-specific documentation for __format__ methods' updated_at = user = 'https://github.com/smontanaro' ``` bugs.python.org fields: ```python activity = actor = 'cheryl.sabella' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'skip.montanaro' dependencies = [] files = [] hgrepos = [] issue_num = 24417 keywords = [] message_count = 1.0 messages = ['245063'] nosy_count = 4.0 nosy_names = ['skip.montanaro', 'eric.smith', 'docs@python', 'cheryl.sabella'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = None url = 'https://bugs.python.org/issue24417' versions = [] ```

[smontanaro]

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 formatspec 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.