gh-69456: Add method to detect if a string contains surrogates

[StanFromIreland]

Request @bitdancer (and maybe @ezio-melotti and @malemburg (looking at devguide))

contains_surrogates is misleading since it does not require more than one, and to me, singular suffers less, though it can be misleading too.

And, should this also be implemented for bytes?

• Issue: Add method to detect if a string contains surrogates #69456

---

📚 Documentation preview 📚: https://cpython-previews--135265.org.readthedocs.build/

[bitdancer]

Thanks for working on this!

_has_surrogates is an internal email library function name, and as such is not a suitable model for the method name for more than one reason. Importantly, it is a bit misleading to say we are detecting 'surrogates', since what we actually want the function to do is detect that a string contains surrogateescape encoded bytes. I'm a bit rusty on the python C code, but if I understand correctly surrogates only appear in the python internal unicode representation if there are in fact escaped bytes, so the function itself is probably correct. I'd like someone with fresher knowledge of the relevant C code to review, though.

But I can give my opinion on the name :) We probably want something like issurrogateescaped to harmonize with the analogous existing string function names. Specifically, this is analogous to istitle, which returns True if and only if the string has at least one capital letter and conforms to the title casing rules. In this case, we return True if and only if the string contains at least one escaped byte.

And no, there is no corresponding method for bytes, since by definition this is something that only has meaning in a unicode string, since surrogateescape is a decode error handler.

[ZeroIntensity]

For what it's worth, changes to builtins (especially ones as prominent as str) need PEPs these days, because they'll have to be reflected across implementations. Perhaps @bitdancer would be willing to author/sponsor one?