Thanks for your contribution @ic4f .

Thank you for approving/merging!

@ic4f

One thing I noticed in this docstring.

Is this correct to say?

The return value i is such that all e in a[:i] have e < x, and all e in
    a[i:] have e >= x.  So if x already appears in the list, a.insert(i, x) will
    insert just before the leftmost x already there.

If a[i:] includes e, and i is the left-most value in the list, then isn't it true instead that:

if x already appears in the list, a.insert(i, x) will insert at the same place as the leftmost x already there.

@petulla, I suppose the alternative wording is not wrong. However, the original seems more correct to me. I think the implied meaning here is insertion point, not insertion index - i.e., if I think of it as a row of items, I'll be inserting before or after an item, not in place of an item (which would be a swap). So, it describes the end result of the insert operation - i.e., what the resulting sequence will be, not the first step in the algorithm to achieve that sequence (in which case insertion index would be appropriate).

I see, that makes sense.

The wording as it is confusing though. I don't think it articulates that case. It does seem like it's giving the insertion point, i, where the element already exists.

If the wording seems not quite right, you might consider opening an issue, see what the community thinks. There's hardly a perfectly worded docstring :)

Where can issues be opened? I only saw the possibility for PRs, which I'm happy to do but an issue would be best.

The issue tracker: https://bugs.python.org/. Also, this is very helpful as a general intro: https://devguide.python.org/#contributing

I agree with @ic4f , open an issue on bpo or email python-dev with your suggestions if you want.