[Python-checkins] cpython (3.4): Issue #21279: Flesh out str.translate docs
zach.ware
python-checkins at python.org
Thu Aug 6 07:06:07 CEST 2015
https://hg.python.org/cpython/rev/ae53bd5decae
changeset: 97298:ae53bd5decae
branch: 3.4
parent: 97295:dda625798111
user: Zachary Ware <zachary.ware at gmail.com>
date: Wed Aug 05 23:54:15 2015 -0500
summary:
Issue #21279: Flesh out str.translate docs
Initial patch by Kinga Farkas, Martin Panter, and John Posner.
files:
Doc/library/stdtypes.rst | 23 ++++++++++++-----------
Objects/unicodeobject.c | 11 ++++++-----
2 files changed, 18 insertions(+), 16 deletions(-)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1976,21 +1976,22 @@
"They're Bill's Friends."
-.. method:: str.translate(map)
-
- 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.
+.. method:: str.translate(table)
+
+ 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
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -13077,11 +13077,12 @@
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)
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list