# HG changeset patch # Parent 32ee7b9d58c9de2a55128068af060220d4f134df diff -r 32ee7b9d58c9 Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst Tue May 26 21:57:16 2015 +1000 +++ b/Doc/library/stdtypes.rst Tue May 26 13:09:53 2015 +0000 @@ -1466,104 +1466,26 @@ other modules that provide various text related utilities (including regular expression support in the :mod:`re` module). -.. method:: str.capitalize() - - Return a copy of the string with its first character capitalized and the - rest lowercased. - - -.. method:: str.casefold() - - Return a casefolded copy of the string. Casefolded strings may be used for - caseless matching. - - Casefolding is similar to lowercasing but more aggressive because it is - intended to remove all case distinctions in a string. For example, the German - lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already - lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` - converts it to ``"ss"``. - - The casefolding algorithm is described in section 3.13 of the Unicode - Standard. - - .. versionadded:: 3.3 - - -.. method:: str.center(width[, fillchar]) - - Return centered in a string of length *width*. Padding is done using the - specified *fillchar* (default is an ASCII space). The original string is - returned if *width* is less than or equal to ``len(s)``. - - - -.. method:: str.count(sub[, start[, end]]) - - Return the number of non-overlapping occurrences of substring *sub* in the - range [*start*, *end*]. Optional arguments *start* and *end* are - interpreted as in slice notation. - - -.. method:: str.encode(encoding="utf-8", errors="strict") - - Return an encoded version of the string as a bytes object. Default encoding - is ``'utf-8'``. *errors* may be given to set a different error handling scheme. - The default for *errors* is ``'strict'``, meaning that encoding errors raise - a :exc:`UnicodeError`. Other possible - values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, - ``'backslashreplace'`` and any other name registered via - :func:`codecs.register_error`, see section :ref:`error-handlers`. For a - list of possible encodings, see section :ref:`standard-encodings`. - - .. versionchanged:: 3.1 - Support for keyword arguments added. - - -.. method:: str.endswith(suffix[, start[, end]]) - - Return ``True`` if the string ends with the specified *suffix*, otherwise return - ``False``. *suffix* can also be a tuple of suffixes to look for. With optional - *start*, test beginning at that position. With optional *end*, stop comparing - at that position. - - -.. method:: str.expandtabs(tabsize=8) - - Return a copy of the string where all tab characters are replaced by one or - more spaces, depending on the current column and the given tab size. Tab - positions occur every *tabsize* characters (default is 8, giving tab - positions at columns 0, 8, 16 and so on). To expand the string, the current - column is set to zero and the string is examined character by character. If - the character is a tab (``\t``), one or more space characters are inserted - in the result until the current column is equal to the next tab position. - (The tab character itself is not copied.) If the character is a newline - (``\n``) or return (``\r``), it is copied and the current column is reset to - zero. Any other character is copied unchanged and the current column is - incremented by one regardless of how the character is represented when - printed. - - >>> '01\t012\t0123\t01234'.expandtabs() - '01 012 0123 01234' - >>> '01\t012\t0123\t01234'.expandtabs(4) - '01 012 0123 01234' - - -.. method:: str.find(sub[, start[, end]]) - - Return the lowest index in the string where substring *sub* is found, such - that *sub* is contained in the slice ``s[start:end]``. Optional arguments - *start* and *end* are interpreted as in slice notation. Return ``-1`` if - *sub* is not found. - - .. note:: - - The :meth:`~str.find` method should be used only if you need to know the - position of *sub*. To check if *sub* is a substring or not, use the - :keyword:`in` operator:: - - >>> 'Py' in 'Python' - True - +The string methods, in alphabetical order: +:meth:`~str.capitalize`, :meth:`~str.casefold`, :meth:`~str.center`, +:meth:`~str.count`, :meth:`~str.encode`, :meth:`~str.endswith`, +:meth:`~str.expandtabs`, :meth:`~str.find`, :meth:`~str.format`, +:meth:`~str.format_map`, :meth:`~str.index`, :meth:`~str.isalnum`, +:meth:`~str.isalpha`, :meth:`~str.isdecimal`, :meth:`~str.isdigit`, +:meth:`~str.isidentifier`, :meth:`~str.islower`, :meth:`~str.isnumeric`, +:meth:`~str.isprintable`, :meth:`~str.isspace`, :meth:`~str.istitle`, +:meth:`~str.isupper`, :meth:`~str.join`, :meth:`~str.ljust`, +:meth:`~str.lower`, :meth:`~str.lstrip`, :meth:`~str.maketrans`, +:meth:`~str.partition`, :meth:`~str.replace`, :meth:`~str.rfind`, +:meth:`~str.rindex`, :meth:`~str.rjust`, :meth:`~str.rpartition`, +:meth:`~str.rsplit`, :meth:`~str.rstrip`, :meth:`~str.split`, +:meth:`~str.splitlines`, :meth:`~str.startswith`, :meth:`~str.strip`, +:meth:`~str.swapcase`, :meth:`~str.title`, :meth:`~str.translate`, +:meth:`~str.upper`, :meth:`~str.zfill`. + + +String Formatting +----------------- .. method:: str.format(*args, **kwargs) @@ -1597,160 +1519,51 @@ .. versionadded:: 3.2 +Searching and Replacing +----------------------- + +.. method:: str.find(sub[, start[, end]]) + str.rfind(sub[, start[, end]]) + + Return an index in the string where substring *sub* is found, such + that *sub* is contained in the slice ``s[start:end]``. + The lowest possible index is returned for :meth:`find`, and the + highest possible index is returned for :meth:`rfind`. Optional arguments + *start* and *end* are interpreted as in slice notation. Return ``-1`` if + *sub* is not found. + + .. note:: + + These methods should be used only if you need to know the + position of *sub*. To check if *sub* is a substring or not, use the + :keyword:`in` operator:: + + >>> 'Py' in 'Python' + True + + .. method:: str.index(sub[, start[, end]]) - - Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is - not found. - - -.. method:: str.isalnum() - - Return true if all characters in the string are alphanumeric and there is at - least one character, false otherwise. A character ``c`` is alphanumeric if one - of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, - ``c.isdigit()``, or ``c.isnumeric()``. - - -.. method:: str.isalpha() - - Return true if all characters in the string are alphabetic and there is at least - one character, false otherwise. Alphabetic characters are those characters defined - in the Unicode character database as "Letter", i.e., those with general category - property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different - from the "Alphabetic" property defined in the Unicode Standard. - - -.. method:: str.isdecimal() - - Return true if all characters in the string are decimal - characters and there is at least one character, false - otherwise. Decimal characters are those from general category "Nd". This category - includes digit characters, and all characters - that can be used to form decimal-radix numbers, e.g. U+0660, - ARABIC-INDIC DIGIT ZERO. - - -.. method:: str.isdigit() - - Return true if all characters in the string are digits and there is at least one - character, false otherwise. Digits include decimal characters and digits that need - special handling, such as the compatibility superscript digits. Formally, a digit - is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal. - - -.. method:: str.isidentifier() - - Return true if the string is a valid identifier according to the language - definition, section :ref:`identifiers`. - - Use :func:`keyword.iskeyword` to test for reserved identifiers such as - :keyword:`def` and :keyword:`class`. - -.. method:: str.islower() - - Return true if all cased characters [4]_ in the string are lowercase and - there is at least one cased character, false otherwise. - - -.. method:: str.isnumeric() - - Return true if all characters in the string are numeric - characters, and there is at least one character, false - otherwise. Numeric characters include digit characters, and all characters - that have the Unicode numeric value property, e.g. U+2155, - VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property - value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric. - - -.. method:: str.isprintable() - - Return true if all characters in the string are printable or the string is - empty, false otherwise. Nonprintable characters are those characters defined - in the Unicode character database as "Other" or "Separator", excepting the - ASCII space (0x20) which is considered printable. (Note that printable - characters in this context are those which should not be escaped when - :func:`repr` is invoked on a string. It has no bearing on the handling of - strings written to :data:`sys.stdout` or :data:`sys.stderr`.) - - -.. method:: str.isspace() - - Return true if there are only whitespace characters in the string and there is - at least one character, false otherwise. Whitespace characters are those - characters defined in the Unicode character database as "Other" or "Separator" - and those with bidirectional property being one of "WS", "B", or "S". - -.. method:: str.istitle() - - Return true if the string is a titlecased string and there is at least one - character, for example uppercase characters may only follow uncased characters - and lowercase characters only cased ones. Return false otherwise. - - -.. method:: str.isupper() - - Return true if all cased characters [4]_ in the string are uppercase and - there is at least one cased character, false otherwise. - - -.. method:: str.join(iterable) - - Return a string which is the concatenation of the strings in the - :term:`iterable` *iterable*. A :exc:`TypeError` will be raised if there are - any non-string values in *iterable*, including :class:`bytes` objects. The - separator between elements is the string providing this method. - - -.. method:: str.ljust(width[, fillchar]) - - Return the string left justified in a string of length *width*. Padding is - done using the specified *fillchar* (default is an ASCII space). The - original string is returned if *width* is less than or equal to ``len(s)``. - - -.. method:: str.lower() - - Return a copy of the string with all the cased characters [4]_ converted to - lowercase. - - The lowercasing algorithm used is described in section 3.13 of the Unicode - Standard. - - -.. method:: str.lstrip([chars]) - - Return a copy of the string with leading characters removed. The *chars* - argument is a string specifying the set of characters to be removed. If omitted - or ``None``, the *chars* argument defaults to removing whitespace. The *chars* - argument is not a prefix; rather, all combinations of its values are stripped:: - - >>> ' spacious '.lstrip() - 'spacious ' - >>> 'www.example.com'.lstrip('cmowz.') - 'example.com' - - -.. staticmethod:: str.maketrans(x[, y[, z]]) - - This static method returns a translation table usable for :meth:`str.translate`. - - If there is only one argument, it must be a dictionary mapping Unicode - ordinals (integers) or characters (strings of length 1) to Unicode ordinals, - strings (of arbitrary lengths) or None. Character keys will then be - converted to ordinals. - - If there are two arguments, they must be strings of equal length, and in the - resulting dictionary, each character in x will be mapped to the character at - the same position in y. If there is a third argument, it must be a string, - whose characters will be mapped to None in the result. - - -.. method:: str.partition(sep) - - Split the string at the first occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself, and the part - after the separator. If the separator is not found, return a 3-tuple containing - the string itself, followed by two empty strings. + str.rindex(sub[, start[, end]]) + + Like :meth:`find` and :meth:`rfind`, but raise :exc:`ValueError` when + the substring is not found. + + +.. method:: str.startswith(prefix[, start[, end]]) + str.endswith(suffix[, start[, end]]) + + Return ``True`` if string starts with the *prefix* or ends with + the *suffix*, otherwise return ``False``. *prefix* and *suffix* can also + be tuples of prefixes and suffixes to look for. With optional *start*, + test string beginning at that position. With optional *end*, stop comparing + string at that position. + + +.. method:: str.count(sub[, start[, end]]) + + Return the number of non-overlapping occurrences of substring *sub* in the + range [*start*, *end*]. Optional arguments *start* and *end* are + interpreted as in slice notation. .. method:: str.replace(old, new[, count]) @@ -1760,61 +1573,17 @@ occurrences are replaced. -.. method:: str.rfind(sub[, start[, end]]) - - Return the highest index in the string where substring *sub* is found, such - that *sub* is contained within ``s[start:end]``. Optional arguments *start* - and *end* are interpreted as in slice notation. Return ``-1`` on failure. - - -.. method:: str.rindex(sub[, start[, end]]) - - Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not - found. - - -.. method:: str.rjust(width[, fillchar]) - - Return the string right justified in a string of length *width*. Padding is - done using the specified *fillchar* (default is an ASCII space). The - original string is returned if *width* is less than or equal to ``len(s)``. - - -.. method:: str.rpartition(sep) - - Split the string at the last occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself, and the part - after the separator. If the separator is not found, return a 3-tuple containing - two empty strings, followed by the string itself. - - -.. method:: str.rsplit(sep=None, maxsplit=-1) - - Return a list of the words in the string, using *sep* as the delimiter string. - If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* - ones. If *sep* is not specified or ``None``, any whitespace string is a - separator. Except for splitting from the right, :meth:`rsplit` behaves like - :meth:`split` which is described in detail below. - - -.. method:: str.rstrip([chars]) - - Return a copy of the string with trailing characters removed. The *chars* - argument is a string specifying the set of characters to be removed. If omitted - or ``None``, the *chars* argument defaults to removing whitespace. The *chars* - argument is not a suffix; rather, all combinations of its values are stripped:: - - >>> ' spacious '.rstrip() - ' spacious' - >>> 'mississippi'.rstrip('ipz') - 'mississ' - +Splitting and Joining +--------------------- .. method:: str.split(sep=None, maxsplit=-1) + str.rsplit(sep=None, maxsplit=-1) Return a list of the words in the string, using *sep* as the delimiter - string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, - the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not + string. If *maxsplit* is given, at most *maxsplit* splits + are done, the *leftmost* ones for :meth:`split`, + and the *rightmost* ones for :meth:`rsplit`. Thus, + the list will have at most ``maxsplit+1`` elements. If *maxsplit* is not specified or ``-1``, then there is no limit on the number of splits (all possible splits are made). @@ -1916,43 +1685,167 @@ ['Two lines', ''] -.. method:: str.startswith(prefix[, start[, end]]) - - Return ``True`` if string starts with the *prefix*, otherwise return ``False``. - *prefix* can also be a tuple of prefixes to look for. With optional *start*, - test string beginning at that position. With optional *end*, stop comparing - string at that position. - - -.. method:: str.strip([chars]) - - Return a copy of the string with the leading and trailing characters removed. - The *chars* argument is a string specifying the set of characters to be removed. - If omitted or ``None``, the *chars* argument defaults to removing whitespace. - The *chars* argument is not a prefix or suffix; rather, all combinations of its - values are stripped:: - - >>> ' spacious '.strip() - 'spacious' - >>> 'www.example.com'.strip('cmowz.') - 'example' - - The outermost leading and trailing *chars* argument values are stripped - from the string. Characters are removed from the leading end until - reaching a string character that is not contained in the set of - characters in *chars*. A similar action takes place on the trailing end. - For example:: - - >>> comment_string = '#....... Section 3.2.1 Issue #32 .......' - >>> comment_string.strip('.#! ') - 'Section 3.2.1 Issue #32' - - -.. method:: str.swapcase() - - Return a copy of the string with uppercase characters converted to lowercase and - vice versa. Note that it is not necessarily true that - ``s.swapcase().swapcase() == s``. +.. method:: str.partition(sep) + str.rpartition(sep) + + Split the string at an occurrence of *sep*, and return a 3-tuple + containing the part before the separator, the separator itself, and the part + after the separator. The first possible occurence is used for + :meth:`partition`, and the last possible occurrence is used for + :meth:`rpartition`. If the separator is not found, :meth:`partition` + returns a 3-tuple containing the string itself, followed by two empty + strings, and :meth:`rpartition` returns a 3-tuple containing two empty + strings, followed by the string itself. + + +.. method:: str.join(iterable) + + Return a string which is the concatenation of the strings in the + :term:`iterable` *iterable*. A :exc:`TypeError` will be raised if there are + any non-string values in *iterable*, including :class:`bytes` objects. The + separator between elements is the string providing this method. + + +String Classification +--------------------- + +.. method:: str.isalpha() + + Return true if all characters in the string are alphabetic and there is at least + one character, false otherwise. Alphabetic characters are those characters defined + in the Unicode character database as "Letter", i.e., those with general category + property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different + from the "Alphabetic" property defined in the Unicode Standard. + + +.. method:: str.isdecimal() + + Return true if all characters in the string are decimal + characters and there is at least one character, false + otherwise. Decimal characters are those from general category "Nd". This category + includes digit characters, and all characters + that can be used to form decimal-radix numbers, e.g. U+0660, + ARABIC-INDIC DIGIT ZERO. + + +.. method:: str.isdigit() + + Return true if all characters in the string are digits and there is at least one + character, false otherwise. Digits include decimal characters and digits that need + special handling, such as the compatibility superscript digits. Formally, a digit + is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal. + + +.. method:: str.isnumeric() + + Return true if all characters in the string are numeric + characters, and there is at least one character, false + otherwise. Numeric characters include digit characters, and all characters + that have the Unicode numeric value property, e.g. U+2155, + VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property + value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric. + + +.. method:: str.isalnum() + + Return true if all characters in the string are alphanumeric and there is at + least one character, false otherwise. A character ``c`` is alphanumeric if one + of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, + ``c.isdigit()``, or ``c.isnumeric()``. + + +.. method:: str.isidentifier() + + Return true if the string is a valid identifier according to the language + definition, section :ref:`identifiers`. + + Use :func:`keyword.iskeyword` to test for reserved identifiers such as + :keyword:`def` and :keyword:`class`. + + +.. method:: str.islower() + + Return true if all cased characters [4]_ in the string are lowercase and + there is at least one cased character, false otherwise. + + +.. method:: str.isupper() + + Return true if all cased characters [4]_ in the string are uppercase and + there is at least one cased character, false otherwise. + + +.. method:: str.istitle() + + Return true if the string is a titlecased string and there is at least one + character, for example uppercase characters may only follow uncased characters + and lowercase characters only cased ones. Return false otherwise. + + +.. method:: str.isspace() + + Return true if there are only whitespace characters in the string and there is + at least one character, false otherwise. Whitespace characters are those + characters defined in the Unicode character database as "Other" or "Separator" + and those with bidirectional property being one of "WS", "B", or "S". + + +.. method:: str.isprintable() + + Return true if all characters in the string are printable or the string is + empty, false otherwise. Nonprintable characters are those characters defined + in the Unicode character database as "Other" or "Separator", excepting the + ASCII space (0x20) which is considered printable. (Note that printable + characters in this context are those which should not be escaped when + :func:`repr` is invoked on a string. It has no bearing on the handling of + strings written to :data:`sys.stdout` or :data:`sys.stderr`.) + + +Case Manipulation +----------------- + +.. method:: str.lower() + + Return a copy of the string with all the cased characters [4]_ converted to + lowercase. + + The lowercasing algorithm used is described in section 3.13 of the Unicode + Standard. + + +.. method:: str.upper() + + Return a copy of the string with all the cased characters [4]_ converted to + uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s`` + contains uncased characters or if the Unicode category of the resulting + character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, + titlecase). + + The uppercasing algorithm used is described in section 3.13 of the Unicode + Standard. + + +.. method:: str.casefold() + + Return a casefolded copy of the string. Casefolded strings may be used for + caseless matching. + + Casefolding is similar to lowercasing but more aggressive because it is + intended to remove all case distinctions in a string. For example, the German + lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already + lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` + converts it to ``"ss"``. + + The casefolding algorithm is described in section 3.13 of the Unicode + Standard. + + .. versionadded:: 3.3 + + +.. method:: str.capitalize() + + Return a copy of the string with its first character capitalized and the + rest lowercased. .. method:: str.title() @@ -1986,33 +1879,24 @@ "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. - - 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). - - -.. method:: str.upper() - - Return a copy of the string with all the cased characters [4]_ converted to - uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s`` - contains uncased characters or if the Unicode category of the resulting - character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, - titlecase). - - The uppercasing algorithm used is described in section 3.13 of the Unicode - Standard. +.. method:: str.swapcase() + + Return a copy of the string with uppercase characters converted to lowercase and + vice versa. Note that it is not necessarily true that + ``s.swapcase().swapcase() == s``. + + +Padding and Stripping +--------------------- + +.. method:: str.ljust(width[, fillchar]) + str.rjust(width[, fillchar]) + str.center(width[, fillchar]) + + Return the string left or right justified, or + centered, in a string of length *width*. Padding is + done using the specified *fillchar* (default is an ASCII space). The + original string is returned if *width* is less than or equal to ``len(s)``. .. method:: str.zfill(width) @@ -2031,6 +1915,114 @@ '-0042' +.. method:: str.expandtabs(tabsize=8) + + Return a copy of the string where all tab characters are replaced by one or + more spaces, depending on the current column and the given tab size. Tab + positions occur every *tabsize* characters (default is 8, giving tab + positions at columns 0, 8, 16 and so on). To expand the string, the current + column is set to zero and the string is examined character by character. If + the character is a tab (``\t``), one or more space characters are inserted + in the result until the current column is equal to the next tab position. + (The tab character itself is not copied.) If the character is a newline + (``\n``) or return (``\r``), it is copied and the current column is reset to + zero. Any other character is copied unchanged and the current column is + incremented by one regardless of how the character is represented when + printed. + + >>> '01\t012\t0123\t01234'.expandtabs() + '01 012 0123 01234' + >>> '01\t012\t0123\t01234'.expandtabs(4) + '01 012 0123 01234' + + +.. method:: str.strip([chars]) + str.lstrip([chars]) + str.rstrip([chars]) + + Return a copy of the string with leading and/or trailing characters + removed. Both leading and trailing characters are removed by + :meth:`strip`, only leading characters are removed by :meth:`lstrip`, + and only trailing characters are removed by :meth:`rstrip`. + The *chars* argument is a string specifying the set of characters to be removed. + If omitted or ``None``, the *chars* argument defaults to removing whitespace. + The *chars* argument is not a prefix or suffix; rather, all combinations of its + values are stripped:: + + >>> ' spacious '.strip() + 'spacious' + >>> ' spacious '.lstrip() + 'spacious ' + >>> ' spacious '.rstrip() + ' spacious' + >>> 'www.example.com'.strip('cmowz.') + 'example' + >>> 'www.example.com'.lstrip('cmowz.') + 'example.com' + >>> 'mississippi'.rstrip('ipz') + 'mississ' + + The outermost leading and/or trailing *chars* argument values are stripped + from the string. Characters are removed from the leading end until + reaching a string character that is not contained in the set of + characters in *chars*. A similar action takes place on the trailing end. + For example:: + + >>> comment_string = '#....... Section 3.2.1 Issue #32 .......' + >>> comment_string.strip('.#! ') + 'Section 3.2.1 Issue #32' + + +Translation and Encoding +------------------------ + +.. 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. + + 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). + + +.. staticmethod:: str.maketrans(x[, y[, z]]) + + This static method returns a translation table usable for :meth:`str.translate`. + + If there is only one argument, it must be a dictionary mapping Unicode + ordinals (integers) or characters (strings of length 1) to Unicode ordinals, + strings (of arbitrary lengths) or None. Character keys will then be + converted to ordinals. + + If there are two arguments, they must be strings of equal length, and in the + resulting dictionary, each character in x will be mapped to the character at + the same position in y. If there is a third argument, it must be a string, + whose characters will be mapped to None in the result. + + +.. method:: str.encode(encoding="utf-8", errors="strict") + + Return an encoded version of the string as a bytes object. Default encoding + is ``'utf-8'``. *errors* may be given to set a different error handling scheme. + The default for *errors* is ``'strict'``, meaning that encoding errors raise + a :exc:`UnicodeError`. Other possible + values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, + ``'backslashreplace'`` and any other name registered via + :func:`codecs.register_error`, see section :ref:`error-handlers`. For a + list of possible encodings, see section :ref:`standard-encodings`. + + .. versionchanged:: 3.1 + Support for keyword arguments added. + + .. _old-string-formatting: