I think I'm fine with this addition. However, because we talk about "backported" interface, we shouldn't push this until it's effectively backported (at least once). I'm actually unsure about the expanded docs. For instance:

I feel that the "note" boxes are way too intrusive... I think it's more important to have the note about the surprising values rather than the note on the availability (the versionadded should be enough). OTOH, if you ever add more protections, we'll have a huge block of notes, almost always the same. Here's what I can suggest: a simple .. seealso:: which refers to a section about "Availability testing" which indicates that some features are included in micro versions instead of .0 versions. That would reduce the vertical span of the page and be more readable for users in general. WDYT?

I think I'm fine with this addition. However, because we talk about "backported" interface, we shouldn't push this until it's effectively backported (at least once).

@picnixz I'm reading that as merging at least one of the unmerged backports of #139234 first — sure.

I feel that the "note" boxes are way too intrusive...

It's got a bit less loud in the meantime when adding the ! earlier — less bold and blue now:

I think it's more important to have the note about the surprising values rather than the note on the availability (the versionadded should be enough).

So there is a threshold where above a note gets its own box and below a box takes too much attention, makes sense.

OTOH, if you ever add more protections, we'll have a huge block of notes, almost always the same.

It would be multiple smaller blocks, not one huge block though. It's a bit less scary than that.

Btw I have no plans of adding more, new API like that will only appear if there is no way around it.

Here's what I can suggest: a simple .. seealso:: which refers to a section about "Availability testing" which indicates that some features are included in micro versions instead of .0 versions. That would reduce the vertical span of the page and be more readable for users in general. WDYT?

Personally I think that see also requires an additional click and additional energy and that alone will many users stop from ever noticing. (I also believe readability is not in danger currently.) Let me demo what we get when taking the .. note:: markers out and turning these notes back to text. Someone reading the whole method description will get the memo then, and it will not be as loud. Push coming up in a minute or two…

@picnixz pushed.

@picnixz how do you like the new version?

I'm sorry but I don't have a lot of time to look at the Expat related issues/PRs. At first glance it looks fine (less visual distraction).

@hugovk As someone who has better insight on accessibility & co, what would you suggest here?

@hugovk thanks for the review! How about now?

And backport this to 3.13?

Actually, we didn't backported the methods to prior versions yet. I am currently starting my new work so I didn'tt have much time to focus on those PRs (currently, only main contains these new APIs)

OK, so should this not have been merged yet? It's only in the 3.15 docs for now, so not such a big deal if they're coming soon-ish.

Yes, I should have added the DO-NOT-MERGE, my fault (we discussed it in the comments but it should have been mentioned more explicitly). It's not really important as I plan to backport the PRs next week (but my work may take me some time) (half of them are ready, the other half isn't backported yet)

OK, let's leave this in main for now and do the backports later. Good luck with your new work!

OK, let's leave this in main for now and do the backports later.

@hugovk good plan, there is no real damage done, no worries.

Good luck with your new work!

From me as well! 🥂