Suggested changes to Lib Ref Manual: Sequence Types --...(3.6 for 2.5)

(These are mostly based on an issue posted on c.l.p. The Plone
Archetypes package (which I know nothing of) was reported as suggesting
that users pass sys.maxint, to indicate 'insert at end', to one of their
functions that uses .insert.  A user with an AMD64 did that ... and I
could not find doc proof that the crash was not a Python bug.)

Main section:

Before the operation list, change "n, i and j are integers:" to "n, i,
j, and k are integers:"

After the above, add "An implementation may limit the range of position
indexes (some uses of i below)."  I do not know if this limitation,
actual for CPython is documented elsewhere, but it should be here.  In
particular, i is used as both position and slice index.

Consider using i only as a magnitude-limited position index (an
'index-sized integer' as one error message puts it) and j,k,l for
unlimited slice and other integers. This would slightly change the
suggestions above and entail replacements in the table here and in
following subsections.

Mutable Sequence Types

In 3.0, .count and .index are general sequence methods and should be
moved up to that section.  (For .index, parameters i & j are not
(limited) position indexes but simply integers for comparison.  The
notation change suggested above would make this clear without one having
to experiment or infer from the comparison rule.)

The line "s.insert(i, x)  same as s[i:i] = [x]" is not true when i is
outside the range of allow position indexes.  If i is not defined as a
limited range integer (and the implementation not changed ;-) add a
footnote "only when i is within the range of allowed position indexes."

Is there a policy on documenting possible operation-specific exceptions?
 I consider them part of the interface.  Or should I bring this up on pydev?

For 3.0, footnotes 3 and 7 (in this subsection) document 2, for 4
different operations.  Here are a couple more related to this issue.

In the main section, for s[i]:
2.x IndexError: cannot fit 'long' into an index-sized integer
3.0 IndexError: cannot fit 'int' into an index-sized integer

In the subsection, for s.insert(i,x):
2.x OverflowError: long int too large to convert to int
3.0 OverflowError: Python int too large to convert to C ssize_t

I actually think the OverflowError should be changed to IndexError since
the problem is the same in both cases, but that is a different issue.

Please bring it up on python-dev.

Had this actually been brought up?

There were two somewhat independent sections to my post:

1. Specific suggested edits to a particular section of the manual.  At
least some are straightforward. As of 3.0.1, they have not been made and
I presume that is still true.

Georg, if I grab a copy from svn, edit (respecting .rst markup), and
post here, will you diff, review (and possibly further edit to taste)
and apply? If so, can I start with the current 3.1 version ('branch') or
do you prefer the 2.7 version ('trunk', though I think of it the opposite).

2. A general question re documenting exceptions with specific examples
from the same section.  I presume that is Georg suggested I take to
py-dev, but I waited for an 'appropriate' time when there was a 'hot'
issue being discussed and then forgot.  I will try to remember, soon,
when the current filename controversy cools a bit.

> Georg, if I grab a copy from svn, edit (respecting .rst markup), and
> post here, will you diff, review (and possibly further edit to taste)
> and apply? If so, can I start with the current 3.1 version ('branch') or
> do you prefer the 2.7 version ('trunk', though I think of it the
> opposite).

Yes, I'll be happy to review, edit and commit any patch you send me.
If stuff is applicable to trunk (2.7), please do diffs versus trunk --
this helps our merging infrastructure.

> 2. A general question re documenting exceptions with specific examples
> from the same section.  I presume that is Georg suggested I take to
> py-dev, but I waited for an 'appropriate' time when there was a 'hot'
> issue being discussed and then forgot.  I will try to remember, soon,
> when the current filename controversy cools a bit.

Okay :)

Added the i,j,k notes

Left out the processor word size and C-type specifications in-part because it is an implementation detail subject to change.  Another reason is that it doesn't apply to necessarily to all sequences.  Slices take arbitrary objects and with applied to an object's __getitem__, the object itself is responsible for handling it.  Also, the size limits are already reflected in the maximum sizes for the object (a list can't get bigger that Py_ssize_t, so of course, its indicies are similarly bounded).  Adding more text here is leaning towards over-specification of implementation specific details and make the docs harder to read while not adding anything truly helpful.

In particular, it is more harmful than helpful to focus on the edge case where "s.insert(i, x) is not the same as s[i:i] = [x]" when i==sys.maxsize-1.

See r3292.