[issue12874] Rearrange descriptions of builtin types
New submission from Nick Coghlan <ncoghlan@gmail.com>: Section 4 of the Standard Library reference currently includes the two following sections (amongst others): 4.6. Sequence Types — str, bytes, bytearray, list, tuple, range 4.9. memoryview type This is crazy - memoryview, a fairly niche type, gets its own second tier section on the main table of contents, while str, one of the most important types in Python, is tucked away under the generic "Sequence Type" heading? I propose that these sections be rearranged as: 4.6 Sequence Types - list, tuple, range 4.7 Text Types - str 4.8 Binary Data Types - bytes, bytearray, memoryview The Set Types and Mapping Types sections would slide down to sections 4.9 and 4.10 to make room for the two new sections. ---------- assignee: docs@python components: Documentation messages: 143284 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Rearrange descriptions of builtin types versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- title: Rearrange descriptions of builtin types -> Rearrange descriptions of builtin types in the Library reference _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Better titles for the proposed new sections: 4.7 Text Data - str 4.8 Binary Data - bytes, bytearray, memoryview ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: I agree on the subdivision, but I think they should still be grouped together somehow, since these all really *do* share some interfaces: __getitem__ (with slicing), __iter__, __len__, at least; arguably __contains__; probably some others (see collections/abc.py). ---------- nosy: +gvanrossum _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Putting the new sections on tier 2 makes a big difference in discoverability, since that's the lowest level the main ToC page shows. Perhaps just including the phrase "Sequence Type" in the new section titles would provide enough logical grouping? Something like: 4.6 Sequence Types - list, tuple, range 4.7 Text Sequence Type - str 4.8 Binary Data Sequence Types - bytes, bytearray, memoryview ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: That sounds fine. Or list most of them at tier 2: 4.6 Sequence Types - list, tuple, range, str, bytes and friends 4.6.1 Sequence containers - list, tuple, range 4.6.2 Text Sequence Type - str 4.6.3 Binary Data Sequence Types - bytes, bytearray, memoryview Although including range() here feels a bit odd? (It's a much more specialized type -- actually the same can be said for memoryview.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 'Sequence Types - list, tuple, str, bytes, etc' *might* work, but I think part of the problem is that str's brevity is actually a downside in this case. I know I missed it when I was scanning the ToC earlier (I wanted to check if the internal Unicode repr for narrow builds was documented at all - it doesn't appear to be). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: How about "list, tuple, text and binary strings" ? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: I believe this is a duplicate of #4966. ---------- nosy: +ezio.melotti resolution: -> duplicate stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- title: Rearrange descriptions of builtin types -> Rearrange descriptions of builtin types in the Library reference _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Better titles for the proposed new sections: 4.7 Text Data - str 4.8 Binary Data - bytes, bytearray, memoryview ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: I agree on the subdivision, but I think they should still be grouped together somehow, since these all really *do* share some interfaces: __getitem__ (with slicing), __iter__, __len__, at least; arguably __contains__; probably some others (see collections/abc.py). ---------- nosy: +gvanrossum _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Putting the new sections on tier 2 makes a big difference in discoverability, since that's the lowest level the main ToC page shows. Perhaps just including the phrase "Sequence Type" in the new section titles would provide enough logical grouping? Something like: 4.6 Sequence Types - list, tuple, range 4.7 Text Sequence Type - str 4.8 Binary Data Sequence Types - bytes, bytearray, memoryview ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: That sounds fine. Or list most of them at tier 2: 4.6 Sequence Types - list, tuple, range, str, bytes and friends 4.6.1 Sequence containers - list, tuple, range 4.6.2 Text Sequence Type - str 4.6.3 Binary Data Sequence Types - bytes, bytearray, memoryview Although including range() here feels a bit odd? (It's a much more specialized type -- actually the same can be said for memoryview.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 'Sequence Types - list, tuple, str, bytes, etc' *might* work, but I think part of the problem is that str's brevity is actually a downside in this case. I know I missed it when I was scanning the ToC earlier (I wanted to check if the internal Unicode repr for narrow builds was documented at all - it doesn't appear to be). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Guido van Rossum <guido@python.org> added the comment: How about "list, tuple, text and binary strings" ? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: I believe this is a duplicate of #4966. ---------- nosy: +ezio.melotti resolution: -> duplicate stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12874> _______________________________________
participants (3)
-
Ezio Melotti -
Guido van Rossum
-
Nick Coghlan