[New-bugs-announce] [issue4966] Improving Lib Doc Sequence Types Section

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at udel.edu>:

Issues and suggestions for Python Standard Library / Built-in Types /
"Sequence Types — str, bytes, bytearray, list, tuple, range"

1. Put subsections in the same order as in the title and main section. 
In particular, move bytes/bytearray subsection up to follow string
subsection and move range subsection down to bottom of this grouping.

2. String paragraph (the second) ends with the rather wordy sentence
"In addition to the functionality described here, there are also
string-specific methods described in the String Methods section."
where 'String Methods' is a forward link to that subsection.
Add similar possibly less wordy sentence-links for other types.

In particular, end next (byte/bytearray) paragraph with something like
"For specific methods, see String Methods and Bytes and Byte Array
Methods. For bytearrays, also see Mutable Sequence Types."

End the list/tuple paragraph after the Warning with
"For list methods, see Mutable Sequence Types."

After the following range paragraph, the following could be added:
"For more, see Range Type."
However, there is almost nothing more said (perhaps there was before
range objects were stripped down), so I suggest deleting that subsection
and adding anything more that is not duplication to the end of the
beginning section's range paragraph.  If tuples do not need their own
section, range needs one even less.

3. Bytes and Byte Array Method subsection correctly says that bytes and
bytearrays do not have (senseless) .encode but neglects to document the
corresponding inverse .decode method (while it does mention the
specialized .fromhex decoding method).

Also add .isdecimal, .isnumeric, .isprintable, and .maketrans to the
list of exceptions in the first sentence. (Based on dir(str), dir(bytes)
in 3.0)

4. I see three problems with the current documentation of count and
index methods.
a)  They are documented under both String Methods and Mutable Sequences.
 They do not really belong in the latter, which lists "additional
operations that allow in-place modification of the object", because they
do not mutate.
b) Tuples do not have their own a section, but (unlike range objects) do
have a couple of methods: count and index.  Being neither string-like
nor mutable, their having methods is undocumented.
c) Bytearrays, on the other hand, are both string-like and mutable.  So
they are (mis)documented as having two slightly different versions of
these methods. (They actually use the string-like definition, of course.)

Consequently, the definitions of count and index in the Mutable Sequence
subsection are not mutable sequence definitions but are really
list/tuple definitions.  So I suggest one of two variations:
A) In the main section, add the list/tuple version of .count() and
.index() to the table of common sequence operations with a footnote
either explaining the difference for the string group or referring to
String Methods.
B) In the main section, add both versions to the table with footnotes
explaining which is which.

The count/index/tuple doc issue has come up more than once on c.l.p.

----------
assignee: georg.brandl
components: Documentation
messages: 79988
nosy: georg.brandl, tjreedy
severity: normal
status: open
title: Improving Lib Doc Sequence Types Section
versions: Python 3.0, Python 3.1

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