Maybe this could say something like “Operations/methods that involve iteration are generally not atomic, except when used with specific built-in types”, and iteration itself can be moved here?
Mentioning iteration might help people make sense of this, i.e. it's no longer two arbitrary lists of operations/methods.

Then thebad section below would be left only with examples of “manually” combining multiple operations.

I don't know how I feel about this. "Operations/methods that involve iteration are generally not atomic" is probably not a mnemonic we want people to use, because there are methods that are atomic but traverse the list. Granted most of those are ones that also mutate it, but e.g.list.copy doesn't.

But the idea of separating iteration from manually combining multiple operations is good. Maybe we should do just that?

Sounds good.
(I guess it's “operations that involve arbitrary iterators and/or comparison functions”, but that's too long; readers whom that would help can figure it out from the list.)

As for iteration, it sounds like the guarantees are the same for single-threaded code: iteration of a list that is being modified may skip elements or yield repeated elements, but will not crash or produce elements that were never part of the list. Is that right?

Is this the place to document list iterators -- i.e. what happens if you use a sharediterator in several threads?

I've completely reworded the docs to account for lock-free operations. Is this better?

I think documenting iterators should be done in theIterator docs, not really individually for each iterator type.

This is getting long enough that maybe it deserves to be in its own page in the reference docs, along with thread-safety notes for all the builtin types. Then we can link to those reference docs from here.

I think our hope when we originally wanted to include these notes directly in the docs for the builtins was that these notes would be pretty short. But it turns out there are a decent number of caveats and that hope might not be realistic.

I agree with this. Splitting everything out in a new page in the reference docs and then cross-linking sounds like the better approach, especially sincedict docs are going to be even longer.@encukou What do you think?

Hi! Sorry I missed the notification.
Either way works for me. We can reorganize the docs after the content is in -- it'll be easier to get the right structure then.

Ok, let's get this in as-is and once we have more built-in types (I havedict andset PRs ready to go), we'll have a better picture of how the new document should look like.

Sounds good to me then. Maybe let's wait to backport until we're done with the standard library types? But do whatever makes the most sense to you.

Is "intermediate states" correct, or is it just that readers might observe the state either before or after concurrent modification? The way it's written now a very literal-minded reader might conclude that a reader might observe a torn read or other C data race.

It's not about data races, it's about intermediate states when the lock-free operations race with operations that touch multiple elements. For example, iflist.index andlist.reverse race with one another (I know, bad example, becauselist.reverse does have a data race, but let's assume that gets fixed),list.index might return the reversed index, even though some elements might not have been reversed yet.

It's not clear to me what "intermediate states" means here. See my comment above. Would help maybe to clarify globally (i.e. somewhere not in the list docs) what observing an object in an intermediate state means. Is any possible layout of the list while it's being processed possible?

Maybe a glossary reference is useful here? Something like:

per-object lock: In free-threading builds ... Whereas in GIL-enabled builds ...

It is safe in the sense that it won't corrupt the list, but should we also mention that it results in a race condition?