ENH: support str translate for StringMethods

Author: mortada

doc/source/api.rst

@@ -556,6 +556,7 @@ strings and apply several methods to it. These can be acccessed like
    Series.str.strip
    Series.str.swapcase
    Series.str.title
+   Series.str.translate
    Series.str.upper
    Series.str.wrap
    Series.str.zfill

doc/source/text.rst

@@ -269,6 +269,7 @@ Method Summary
     :meth:`~Series.str.capitalize`,Equivalent to ``str.capitalize``
     :meth:`~Series.str.swapcase`,Equivalent to ``str.swapcase``
     :meth:`~Series.str.normalize`,Return Unicode normal form. Equivalent to ``unicodedata.normalize``
+    :meth:`~Series.str.translate`,Equivalent to ``str.translate``
     :meth:`~Series.str.isalnum`,Equivalent to ``str.isalnum``
     :meth:`~Series.str.isalpha`,Equivalent to ``str.isalpha``
     :meth:`~Series.str.isdigit`,Equivalent to ``str.isdigit``

doc/source/whatsnew/v0.16.1.txt

@@ -39,6 +39,7 @@ Enhancements
 
 - Added ``StringMethods.capitalize()`` and ``swapcase`` which behave as the same as standard ``str`` (:issue:`9766`)
 - ``DataFrame.diff`` now takes an ``axis`` parameter that determines the direction of differencing (:issue:`9727`)
+- Added support for ``StringMethods.translate()`` (:issue:`10052`)
 - Added ``StringMethods`` (.str accessor) to ``Index`` (:issue:`9068`)
 - Added ``StringMethods.normalize()`` which behaves the same as standard :func:`unicodedata.normalizes` (:issue:`10031`)
 

pandas/core/strings.py

@@ -861,6 +861,44 @@ def str_wrap(arr, width, **kwargs):
     return _na_map(lambda s: '\n'.join(tw.wrap(s)), arr)
 
 
+def str_translate(arr, table, deletechars=None):
+    """
+    Map all characters in the string through the given mapping table.
+    Equivalent to standard :meth:`str.translate`. Note that the optional
+    argument deletechars is only valid if you are using python 2. For python 3,
+    character deletion should be specified via the table argument.
+
+    Parameters
+    ----------
+    table : dict (python 3), str or None (python 2)
+        In python 3, table is a mapping of Unicode ordinals to Unicode ordinals,
+        strings, or None. Unmapped characters are left untouched. Characters
+        mapped to None are deleted. :meth:`str.maketrans` is a helper function
+        for making translation tables.
+        In python 2, table is either a string of length 256 or None. If the
+        table argument is None, no translation is applied and the operation
+        simply removes the characters in deletechars. :func:`string.maketrans`
+        is a helper function for making translation tables.
+    deletechars : str, optional (python 2)
+        A string of characters to delete. This argument is only valid
+        in python 2.
+
+    Returns
+    -------
+    translated : Series/Index of objects
+    """
+    if deletechars is None:
+        f = lambda x: x.translate(table)
+    else:
+        from pandas import compat
+        if compat.PY3:
+            raise ValueError("deletechars is not a valid argument for "
+                             "str.translate in python 3. You should simply "
+                             "specify character deletions in the table argument")
+        f = lambda x: x.translate(table, deletechars)
+    return _na_map(f, arr)
+
+
 def str_get(arr, i):
     """
     Extract element from lists, tuples, or strings in each element in the
@@ -1165,6 +1203,11 @@ def get_dummies(self, sep='|'):
         result = str_get_dummies(self.series, sep)
         return self._wrap_result(result)
 
+    @copy(str_translate)
+    def translate(self, table, deletechars=None):
+        result = str_translate(self.series, table, deletechars)
+        return self._wrap_result(result)
+
     count = _pat_wrapper(str_count, flags=True)
     startswith = _pat_wrapper(str_startswith, na=True)
     endswith = _pat_wrapper(str_endswith, na=True)

pandas/tests/test_strings.py

@@ -686,6 +686,12 @@ def test_empty_str_methods(self):
         tm.assert_series_equal(empty_str, empty.str.capitalize())
         tm.assert_series_equal(empty_str, empty.str.swapcase())
         tm.assert_series_equal(empty_str, empty.str.normalize('NFC'))
+        if compat.PY3:
+            table = str.maketrans('a', 'b')
+        else:
+            import string
+            table = string.maketrans('a', 'b')
+        tm.assert_series_equal(empty_str, empty.str.translate(table))
 
     def test_ismethods(self):
         values = ['A', 'b', 'Xy', '4', '3A', '', 'TT', '55', '-', '  ']
@@ -966,6 +972,37 @@ def test_pad_fillchar(self):
         with tm.assertRaisesRegexp(TypeError, "fillchar must be a character, not int"):
             result = values.str.pad(5, fillchar=5)
 
+    def test_translate(self):
+        for klass in [Series, Index]:
+            s = klass(['abcdefg', 'abcc', 'cdddfg', 'cdefggg'])
+            if not compat.PY3:
+                import string
+                table = string.maketrans('abc', 'cde')
+            else:
+                table = str.maketrans('abc', 'cde')
+            result = s.str.translate(table)
+            expected = klass(['cdedefg', 'cdee', 'edddfg', 'edefggg'])
+            tm.assert_array_equal(result, expected)
+
+            # use of deletechars is python 2 only
+            if not compat.PY3:
+                result = s.str.translate(table, deletechars='fg')
+                expected = klass(['cdede', 'cdee', 'eddd', 'ede'])
+                tm.assert_array_equal(result, expected)
+
+                result = s.str.translate(None, deletechars='fg')
+                expected = klass(['abcde', 'abcc', 'cddd', 'cde'])
+                tm.assert_array_equal(result, expected)
+            else:
+                with tm.assertRaisesRegexp(ValueError, "deletechars is not a valid argument"):
+                    result = s.str.translate(table, deletechars='fg')
+
+        # Series with non-string values
+        s = Series(['a', 'b', 'c', 1.2])
+        expected = Series(['c', 'd', 'e', np.nan])
+        result = s.str.translate(table)
+        tm.assert_array_equal(result, expected)
+
     def test_center_ljust_rjust(self):
         values = Series(['a', 'b', NA, 'c', NA, 'eeeeee'])