[Python-Dev] [Python-checkins] cpython: Close #4966: revamp the sequence docs in order to better explain the state of (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Tue Aug 21 09:47:28 CEST 2012

On Tue, Aug 21, 2012 at 11:55 AM, Ezio Melotti <ezio.melotti at gmail.com> wrote:

+Sequence Types --- :class:list, :class:tuple, :class:range +================================================================ +

These 3 links in the section title redirect to the functions.html page. I think it would be better if they linked to the appropriate subsection instead, and in the case of the subsections (e.g. "Text Sequence Type --- str") they shouldn't be links. The same comment can be applied to other titles as well.

I made a start on moving the info out of functions.html and adding appropriate noindex entries. str, bytes and bytearray haven't been consolidated at all yet.

++--------------------------+--------------------------------+----------+ +| s * n, n * s | n shallow copies of s | (2)(7) |

I would use 's * n or n * s' here.

Done.

+| s.index(x, [i[, j]]) | index of the first occurence | (8) |

This should be s.index(x[, i[, j]])

Done.

+ + * if concatenating :class:tuple objects, extend a :class:list instead. + + * for other types, investigate the relevant class documentation +

The trailing punctuation of the elements in this list is inconsistent.

Just removed all trailing punctuation from these bullet points for now.

You missed clear() from this list.

The problem was actually index() and count() were missing from the index for the "common sequence operations" table. Added them there, and moved that index above the table.

copy() was missing from the index list for the mutable sequence methods, so I added that.

Also in the "Result" column the descriptions in prose are OK, but I find some of the "same as ..." ones not very readable (or even fairly obscure). (I think I saw something similar in the doc of list.append() too.)

These are all rather old - much of this patch was just moving things around rather than fixing the prose, although there was plenty of the latter, too :)

I tried to improve them a bit.

Is it worth mentioning a function call as an example of syntactic ambiguity? Someone might wonder if foo(a, b, c) is actually passing a 3-elements tuple or 3 distinct values.

Done.

This claim is maybe a bit too strong. I think the main reason to use namedtuples is being able to access the elements via t.name, rather than t[pos], and while this can be useful for basically every heterogeneous tuple, I think that plain tuples are still preferred.

Reworded.

On a separate note, should tuple unpacking be mentioned here? (a link to a separate section of the doc is enough.)

Not really - despite the name, tuple unpacking isn't especially closely related to tuples these days.

I would mention explicitly "in :keyword:for loops" -- ranges don't loop on their own (I think people familiar with Ruby and/or JQuery might get confused here).

Done.

I thought that these two paragraphs were talking about positive and negative start/stop/step until I reached the middle of the second paragraph (the word "indices" wasn't enough to realize that these paragraphs are about indexing/slicing, probably because they are rarely used and I wasn't expecting to find them at this point of the doc). Maybe it's better to move the paragraphs at the bottom of the section.

For the moment, I've just dumped the old range builtin docs into this section. They need a pass to remove the duplication and ensure everything makes sense in context.

+String literals that are part of a single expression and have only whitespace +between them will be implicitly converted to a single string literal. +

Is it a string /literal/ they are converted to? Yup:

ast.dump(compile('"hello world"', '', 'eval', flags=ast.PyCFONLYAST)) "Expression(body=Str(s='hello world'))" ast.dump(compile('"hello" " world"', '', 'eval', flags=ast.PyCFONLYAST)) "Expression(body=Str(s='hello world'))"

Anyway a simple ('foo' 'bar') == 'foobar' example might make this sentence more understandable.

Added.

+There is also no mutable string type, but :meth:str.join or +:class:io.StringIO can be used to efficiently construct strings from +multiple fragments. + str.format() deserves to be mentioned here too.

For the kinds of strings where quadratic growth is a problem, str.format is unlikely to be appropriate.

I noticed that here there's this fairly long section about the "old" string formatting and nothing about the "new" formatting. Maybe this should be moved together with the new formatting doc, so that all the detailed formatting docs are in the same place. (This would also help making this less noticeable)

Probably. There are a lot of structural problems in the current docs, because the layout hasn't previously changed to suit the language design changes.

+While bytes literals and representations are based on ASCII text, bytes +objects actually behave like immutable sequences of integers, with each +value in the sequence restricted such that 0 <= x < 256 (attempts to Earlier you used 0 <= x <= 255.

The current docs are the result of many merges, much of which I didn't write. This is only the start of improving them by breaking away from the old 1.x structure with a few autocratic decisions on my part to establish a new layout that makes more sense given the evolution of the language, especially the big changes in 2.2 and 3.0 :)

Using 'abc'.replace('a', 'f') and b'abc'.replace(b'a', b'f') inline would be better IMHO, given that the current note takes lot of space to explain a trivial concept.

Stylistics edits are always fair game, they don't have to be made by me. While I skipped a lot of your specific suggestions that weren't correcting actual errors, that doesn't mean I'm especially opposed to them, just that I didn't like them enough to implement myself :)

Cheers, Nick.

-- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia

More information about the Python-Dev mailing list