python · StanFromIreland · Jun 8, 2025 · Jun 8, 2025
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -1612,6 +1612,8 @@ category.
 |                          |  :meth:`str.isspace`                      |  :meth:`bytes.isspace`                            |
 |                          +-------------------------------------------+---------------------------------------------------+
 |                          |  :meth:`str.isprintable`                  |                                                   |
+|                          +-------------------------------------------+---------------------------------------------------+
+|                          |  :meth:`str.contains_surrogate`           |                                                   |
 +--------------------------+-------------------------------------------+---------------------------------------------------+
 | Case Manipulation        |  :meth:`str.lower`                        |  :meth:`bytes.lower`                              |
 |                          +-------------------------------------------+---------------------------------------------------+
@@ -2078,6 +2080,15 @@ expression support in the :mod:`re` module).
       False
 
 
+.. method:: str.contains_surrogate()
+
+   Return ``True`` if the string contains any surrogate code points,
+   ``False`` otherwise.
+
+      >>> 'notasurrogate'.contains_surrogate()
+      False
+      >>> '\ud83d\udc0d'.contains_surrogates()
+      True
 
 .. _meth-str-join:
 

@@ -1533,6 +1533,9 @@ def istitle(self):
     def isupper(self):
         return self.data.isupper()
 
+    def contains_surrogate(self):
+        return self.data.contains_surrogate()
+
     def join(self, seq):
         return self.data.join(seq)
 

diff --git a/Lib/test/test_str.py b/Lib/test/test_str.py
@@ -862,17 +862,26 @@ def test_isprintable_invariant(self):
                              category[0] not in ('C', 'Z')
                              or char == ' ')
 
+    def test_contains_surrogates(self):
+        self.assertFalse("hello".contains_surrogate())
+        self.assertFalse("".contains_surrogate())
+        self.assertTrue("\udc80".contains_surrogate())
+        self.assertTrue("\ud800\udfff".contains_surrogate())
+        self.assertTrue("\ud83d\udc0d".contains_surrogate())
+
     def test_surrogates(self):
         for s in ('a\uD800b\uDFFF', 'a\uDFFFb\uD800',
                   'a\uD800b\uDFFFa', 'a\uDFFFb\uD800a'):
             self.assertTrue(s.islower())
             self.assertFalse(s.isupper())
             self.assertFalse(s.istitle())
+            self.assertTrue(s.contains_surrogate())
         for s in ('A\uD800B\uDFFF', 'A\uDFFFB\uD800',
                   'A\uD800B\uDFFFA', 'A\uDFFFB\uD800A'):
             self.assertFalse(s.islower())
             self.assertTrue(s.isupper())
             self.assertTrue(s.istitle())
+            self.assertTrue(s.contains_surrogate())
 
         for meth_name in ('islower', 'isupper', 'istitle'):
             meth = getattr(str, meth_name)

diff --git a/Misc/NEWS.d/next/Library/2025-06-08-14-37-49.gh-issue-69456.KOAy89.rst b/Misc/NEWS.d/next/Library/2025-06-08-14-37-49.gh-issue-69456.KOAy89.rst
@@ -0,0 +1 @@
+Add :meth:`str.contains_surrogate` for surrogate detection.
diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
@@ -12492,6 +12492,32 @@ unicode_isprintable_impl(PyObject *self)
     Py_RETURN_TRUE;
 }
 
+/*[clinic input]
+str.contains_surrogate as unicode_contains_surrogate
+
+Return True if the string contains any surrogate code points, False otherwise.
+
+[clinic start generated code]*/
+
+static PyObject *
+unicode_contains_surrogate_impl(PyObject *self)
+/*[clinic end generated code: output=ec75cbb5265bd886 input=5853bb9f17fc5255]*/
+{
+    Py_ssize_t i, len;
+    Py_UCS4 ch;
+    PyObject *unicode = self;
+
+    len = PyUnicode_GET_LENGTH(unicode);
+
+    for (i = 0; i < len; i++) {
+        ch = PyUnicode_READ_CHAR(unicode, i);
+        if (Py_UNICODE_IS_SURROGATE(ch)) {
+            Py_RETURN_TRUE;
+        }
+    }
+    Py_RETURN_FALSE;
+}
+
 /*[clinic input]
 str.join as unicode_join
 
@@ -14489,6 +14515,7 @@ static PyMethodDef unicode_methods[] = {
     UNICODE_ISALNUM_METHODDEF
     UNICODE_ISIDENTIFIER_METHODDEF
     UNICODE_ISPRINTABLE_METHODDEF
+    UNICODE_CONTAINS_SURROGATE_METHODDEF
     UNICODE_ZFILL_METHODDEF
     {"format", _PyCFunction_CAST(do_string_format), METH_VARARGS | METH_KEYWORDS, format__doc__},
     {"format_map", do_string_format_map, METH_O, format_map__doc__},
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add :meth:`str.contains_surrogate` for surrogate detection.