Using this mechanism for the first time. Please let me know if I'm using it incorrectly.

http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst File Doc/library/stdtypes.rst (right):

http://bugs.python.org/review/21279/diff/13406/Doc/library/stdtypes.rst#newc... Doc/library/stdtypes.rst:1912: Return a copy of the string where all characters have been mapped through the I suggest a revised paragraph, combining this one with the comments made by Terry Reedy. IMO, it's important to point out that a LookupError produced by the translation table does not cause the translate() method to fail. Rather, translate() catches the exception and sends the character, unchanged, to the return string.

Here's my suggested paragraph:

Return a copy of the string *str* in which each character has been mapped through the given translation *table*. The translation table must be a subscriptable object, for instance a list or dictionary; when subscripted (indexed) by a Unicode ordinal (an integer in range(1048576)), the table object can yield a Unicode ordinal, a string, or None -- or else can raise a LookupError. A LookupError (typically, an instance of subclass IndexError or KeyError) is caught by translate; the character is sent, unchanged, to the return string. A character mapped to None is deleted from the return string.

And here's a possible alternative for the first sentence:

Map each character of the string *str* through the given translation *table*, and return the resulting string.

http://bugs.python.org/review/21279/