ascii

Author: Abby VeCasey

pandas/core/strings/accessor.py

@@ -3385,7 +3385,7 @@ def len(self):
     #   cases:
     #       upper, lower, title, capitalize, swapcase, casefold
     #   boolean:
-    #     isalpha, isnumeric isalnum isdigit isdecimal isspace islower isupper istitle
+    #     isalpha, isnumeric isalnum isdigit isdecimal isspace islower isupper istitle isascii
     # _doc_args holds dict of strings to use in substituting casemethod docs
     _doc_args: dict[str, dict[str, str]] = {}
     _doc_args["lower"] = {"type": "lowercase", "method": "lower", "version": ""}
@@ -3465,6 +3465,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3488,6 +3489,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3514,6 +3516,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3546,6 +3549,7 @@ def casefold(self):
     Series.str.isdigit : Check whether all characters are digits.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3571,6 +3575,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3597,6 +3602,7 @@ def casefold(self):
     Series.str.isdigit : Check whether all characters are digits.
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3619,6 +3625,7 @@ def casefold(self):
     Series.str.isdigit : Check whether all characters are digits.
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
     Series.str.istitle : Check whether all characters are titlecase.
 
@@ -3644,6 +3651,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.istitle : Check whether all characters are titlecase.
 
     Examples
@@ -3667,6 +3675,7 @@ def casefold(self):
     Series.str.isdecimal : Check whether all characters are decimal.
     Series.str.isspace : Check whether all characters are whitespace.
     Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isascii : Check whether all characters are ascii.
     Series.str.isupper : Check whether all characters are uppercase.
 
     Examples
@@ -3684,11 +3693,40 @@ def casefold(self):
     3    False
     dtype: bool
     """
+    _shared_docs["isascii"] = """
+    See Also
+    --------
+    Series.str.isalpha : Check whether all characters are alphabetic.
+    Series.str.isnumeric : Check whether all characters are numeric.
+    Series.str.isalnum : Check whether all characters are alphanumeric.
+    Series.str.isdigit : Check whether all characters are digits.
+    Series.str.isdecimal : Check whether all characters are decimal.
+    Series.str.isspace : Check whether all characters are whitespace.
+    Series.str.islower : Check whether all characters are lowercase.
+    Series.str.istitle : Check whether all characters are titlecase.
+    Series.str.isupper : Check whether all characters are uppercase.
+
+    Examples
+    ------------
+    The ``s5.str.isascii`` method checks for whether all characters are ascii characters,
+    which includes digits 0-9, capital and lowercase letters A-Z, and some other
+    special characters.
+
+    >>> s5 = pd.Series(['ö', 'see123', 'hello world', ''])
+    >>> s5.str.isascii()
+    0    False
+    1     True
+    2     True
+    3     True
+    dtype: bool
+    """
+
     _doc_args["isalnum"] = {"type": "alphanumeric", "method": "isalnum"}
     _doc_args["isalpha"] = {"type": "alphabetic", "method": "isalpha"}
     _doc_args["isdigit"] = {"type": "digits", "method": "isdigit"}
     _doc_args["isspace"] = {"type": "whitespace", "method": "isspace"}
     _doc_args["islower"] = {"type": "lowercase", "method": "islower"}
+    _doc_args["isascii"] = {"type": "ascii", "method": "isascii"}
     _doc_args["isupper"] = {"type": "uppercase", "method": "isupper"}
     _doc_args["istitle"] = {"type": "titlecase", "method": "istitle"}
     _doc_args["isnumeric"] = {"type": "numeric", "method": "isnumeric"}
@@ -3720,6 +3758,11 @@ def casefold(self):
         docstring=_shared_docs["ismethods"] % _doc_args["islower"]
         + _shared_docs["islower"],
     )
+    isascii = _map_and_wrap(
+        "isascii",
+        docstring=_shared_docs["ismethods"] % _doc_args["isascii"]
+        + _shared_docs["isascii"],
+    )
     isupper = _map_and_wrap(
         "isupper",
         docstring=_shared_docs["ismethods"] % _doc_args["isupper"]

pandas/core/strings/base.py

@@ -179,6 +179,10 @@ def _str_isalnum(self):
     def _str_isalpha(self):
         pass
 
+    @abc.abstractmethod
+    def _str_isascii(self):
+        pass
+
     @abc.abstractmethod
     def _str_isdecimal(self):
         pass

pandas/core/strings/object_array.py

@@ -454,6 +454,9 @@ def _str_isalnum(self):
 
     def _str_isalpha(self):
         return self._str_map(str.isalpha, dtype="bool")
+    
+    def _str_isascii(self):
+        return self._str_map(str.isascii, dtype="bool")
 
     def _str_isdecimal(self):
         return self._str_map(str.isdecimal, dtype="bool")

pandas/tests/strings/conftest.py

@@ -68,6 +68,7 @@
             "get_dummies",
             "isalnum",
             "isalpha",
+            "isascii",
             "isdecimal",
             "isdigit",
             "islower",

pandas/tests/strings/test_string_array.py

@@ -83,6 +83,7 @@ def test_string_array_numeric_integer_array(nullable_string_dtype, method, expec
     [
         ("isdigit", [False, None, True]),
         ("isalpha", [True, None, False]),
+        ("isascii", [True, None, True]),
         ("isalnum", [True, None, True]),
         ("isnumeric", [False, None, True]),
     ],

pandas/tests/strings/test_strings.py

@@ -159,6 +159,7 @@ def test_empty_str_methods(any_string_dtype):
     # ismethods should always return boolean (GH 29624)
     tm.assert_series_equal(empty_bool, empty.str.isalnum())
     tm.assert_series_equal(empty_bool, empty.str.isalpha())
+    tm.assert_series_equal(empty_bool, empty.str.isascii())
     tm.assert_series_equal(empty_bool, empty.str.isdigit())
     tm.assert_series_equal(empty_bool, empty.str.isspace())
     tm.assert_series_equal(empty_bool, empty.str.islower())
@@ -177,6 +178,7 @@ def test_empty_str_methods(any_string_dtype):
 @pytest.mark.parametrize(
     "method, expected",
     [
+        ("isascii", [True, True, True, True, True, True, True, True, True, True]),
         ("isalnum", [True, True, True, True, True, False, True, True, False, False]),
         ("isalpha", [True, True, True, False, False, False, True, False, False, False]),
         (