Clarify clamping specifications for `sequence.insert`

[yousef-fadli]

https://docs.python.org/3.14/library/array.html#array.array.insert

The documentation for array.array.insert(i, x) does not specify what happens
when i is greater than the length of the array.
for example :

import array

my_array = array.array("i", [1, 2, 3])
my_array.insert(10**9, 4)
print(my_array)

clarifying this behavior in the documentation improves consistency and removes ambiguity

Linked PRs

• gh-143420: Clarify sequence behavior for slice indexes #143422
• [3.14] gh-143420: Clarify sequence behavior for slice indexes (GH-143422) #143701
• [3.13] gh-143420: Clarify sequence behavior for slice indexes (GH-143422) #143703

[terryjreedy]

It inserts at the end of the array, the same as my_array.insert(len(my_array), 4). -1 does not work for this because the insertion is before the current last item.

Would adding or after the last item be sufficient? Note that this could be added to the docstring also.

EDIT: I agree with clarifying since I thought an exception might be raised.

[picnixz]

The list.insert method doesn't have that clarification either so iI think we should also indicate what happens there.

[yousef-fadli]

@terryjreedy
Also, I want to add this case:

import array

my_array = array.array("i", [1, 2, 3])
my_array.insert(-(10**9), 0)
print(my_array)

[skirpichev]

The list.insert method doesn't have that clarification either so iI think we should also indicate what happens there.

It has following statement: "This is equivalent to writing sequence[index:index] = [value]."

That might be the key, as documentation for Common Sequence Operations has following notes for s[i:j]:

3. If i or j is negative, the index is relative to the end of sequence s: len(s) + i or len(s) + j is substituted. But note that -0 is still 0.
4. The slice of s from i to j is defined as the sequence of items with index k such that i <= k < j. If i or j is greater than len(s), use len(s). If i is omitted or None, use 0. If j is omitted or None, use len(s). If i is greater than or equal to j, the slice is empty.

This does explain what happens if index > len(sequence). But not what happens if it's negative and abs(index) > len(sequence). On the ground of note (3) people might think, that index is wrapped like this:

>>> l = [1, 2, 3]
>>> l.insert(-10, 0)  # -10 + 4*3 == 2
>>> l
[1, 2, 0, 3]

I think we should extend note (4) like this:

The slice of s from i to j is defined as the sequence of items with index k such that i <= k < j. If i or j is greater than len(s), use len(s). If i or j is less than -len(s), use 0. If i is omitted or None, use 0. If j is omitted or None, use len(s). If i is greater than or equal to j, the slice is empty.

Nothing should be changed for array docs, as they already said:

Arrays are sequence types and behave very much like lists, except that the type of objects stored in them is constrained.

(Perhaps, we could add a link to the sequence term in the Glossary.)

[yousef-fadli]

@skirpichev

Nothing should be changed for array docs, as they already said:

Yes array is a sequence, but directing the programmers to the accurate function descriptions is better than writing an insufficient description.

For example:
Here in defaultdict, it is mentioned that the remaining functionality is the same as for the dict.

defaultdict is a subclass of the built-in dict class. It overrides one method and adds one writable instance variable. The remaining functionality is the same as for the dict class and is not documented here.

I know that it is not totally the same as an array because the default is a subclass, but for me, when reading the official doc, I find directing the programmer to the accurate descriptions or writing a comprehensive description is better than writing insufficient descriptions.

[picnixz]

It has following statement: "This is equivalent to writing sequence[index:index] = [value]."

Ah I was looking at https://docs.python.org/3/tutorial/datastructures.html actually. My bad. Ok so I think we don't need to change it. array is a mutable sequence and we document this behavior in the mutable sequence specifications. However, we could update the tutorial maybe? (I wouldn't update array.array.insert though).

But yes, we can also update the footnote (4) as it's the specs.

I know that it is not totally the same as an array because the default is a subclass, but for me, when reading the official doc, I find directing the programmer to the accurate descriptions or writing a comprehensive description is better than writing insufficient descriptions.

Verbose documentation is however not preferred because it diverts the reader from the important points. Strictly speaking, the reader is responsible to know the specifications and its assumptions but this is also a huge assumption and we need to weigh the pro and cons of having a huge wall of text.

---

Ideally we should just remove array.insert and link to "mutable sequences". There is nothing fancy in array that needs to be re-documented IMO.

[picnixz]

More precisely, the differences with list methods and array methods is that latter expect the argument to be compatible with the type of the array. Except for methods that were added or changed, it wasn't necessary to document them. Now, removing the links would also result in deadlinks unfortunately. However, I don't want to restate everything that was stated in the common sequence operations in every class that implements the mutable sequence interface.