New submission from Terry J. Reedy <tjre...@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 <rep...@bugs.python.org> <http://bugs.python.org/issue4966> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
