Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rearrange descriptions of builtin types in the Library reference #57083

Closed
ncoghlan opened this issue Aug 31, 2011 · 8 comments
Closed

Rearrange descriptions of builtin types in the Library reference #57083

ncoghlan opened this issue Aug 31, 2011 · 8 comments
Labels
docs Documentation in the Doc dir

Comments

@ncoghlan
Copy link
Contributor

BPO 12874
Nosy @gvanrossum, @ncoghlan, @ezio-melotti

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:

assignee = None
closed_at = <Date 2011-09-01.01:12:28.157>
created_at = <Date 2011-08-31.22:42:40.634>
labels = ['docs']
title = 'Rearrange descriptions of builtin types in the Library reference'
updated_at = <Date 2011-09-01.01:12:28.155>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2011-09-01.01:12:28.155>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-09-01.01:12:28.157>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2011-08-31.22:42:40.634>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 12874
keywords = []
message_count = 8.0
messages = ['143284', '143285', '143286', '143287', '143288', '143290', '143291', '143292']
nosy_count = 4.0
nosy_names = ['gvanrossum', 'ncoghlan', 'ezio.melotti', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12874'
versions = ['Python 3.3']

@ncoghlan
Copy link
Contributor Author

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.

@ncoghlan ncoghlan added the docs Documentation in the Doc dir label Aug 31, 2011
@ncoghlan ncoghlan changed the title Rearrange descriptions of builtin types Rearrange descriptions of builtin types in the Library reference Aug 31, 2011
@ncoghlan
Copy link
Contributor Author

Better titles for the proposed new sections:

4.7 Text Data - str
4.8 Binary Data - bytes, bytearray, memoryview

@gvanrossum
Copy link
Member

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

@ncoghlan
Copy link
Contributor Author

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

@gvanrossum
Copy link
Member

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

@ncoghlan
Copy link
Contributor Author

ncoghlan commented Sep 1, 2011

'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).

@gvanrossum
Copy link
Member

How about "list, tuple, text and binary strings" ?

@ezio-melotti
Copy link
Member

I believe this is a duplicate of bpo-4966.

@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

No branches or pull requests

3 participants