From 79b98df0231ae177a676c8a2631e8143d75d84a7 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Wed, 5 Aug 2015 23:54:15 -0500 Subject: [PATCH] Issue #21279: Flesh out str.translate docs Initial patch by Kinga Farkas, Martin Panter, and John Posner. --- Doc/library/stdtypes.rst | 21 +++++++++++---------- Objects/unicodeobject.c | 11 ++++++----- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 057e3afaf25..05df97c23f1 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1976,21 +1976,22 @@ expression support in the :mod:`re` module). "They're Bill's Friends." -.. method:: str.translate(map) +.. method:: str.translate(table) - Return a copy of the *s* where all characters have been mapped through the - *map* which must be a dictionary of Unicode ordinals (integers) to Unicode - ordinals, strings or ``None``. Unmapped characters are left untouched. - Characters mapped to ``None`` are deleted. + Return a copy of the string in which each character has been mapped through + the given translation table. The table must be an object that implements + indexing via :meth:`__getitem__`, typically a :term:`mapping` or + :term:`sequence`. When indexed by a Unicode ordinal (an integer), the + table object can do any of the following: return a Unicode ordinal or a + string, to map the character to one or more other characters; return + ``None``, to delete the character from the return string; or raise a + :exc:`LookupError` exception, to map the character to itself. You can use :meth:`str.maketrans` to create a translation map from character-to-character mappings in different formats. - .. note:: - - An even more flexible approach is to create a custom character mapping - codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an - example). + See also the :mod:`codecs` module for a more flexible approach to custom + character mappings. .. method:: str.upper() diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 884eaeff26c..e28bae4d2b6 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -13077,11 +13077,12 @@ unicode_maketrans_impl(PyObject *x, PyObject *y, PyObject *z) PyDoc_STRVAR(translate__doc__, "S.translate(table) -> str\n\ \n\ -Return a copy of the string S, where all characters have been mapped\n\ -through the given translation table, which must be a mapping of\n\ -Unicode ordinals to Unicode ordinals, strings, or None.\n\ -Unmapped characters are left untouched. Characters mapped to None\n\ -are deleted."); +Return a copy of the string S in which each character has been mapped\n\ +through the given translation table. The table must implement\n\ +lookup/indexing via __getitem__, for instance a dictionary or list,\n\ +mapping Unicode ordinals to Unicode ordinals, strings, or None. If\n\ +this operation raises LookupError, the character is left untouched.\n\ +Characters mapped to None are deleted."); static PyObject* unicode_translate(PyObject *self, PyObject *table)