rest25/library/string.rst => rest262/library/string.rst
n1- 
2:mod:`string` --- Common string operations
3==========================================
4
5.. module:: string
6   :synopsis: Common string operations.
7
8
9.. index:: module: re
10
n11-The :mod:`string` module contains a number of useful constants and classes, as
n10+The :mod:`string` module contains a number of useful constants and
12-well as some deprecated legacy functions that are also available as methods on
11+classes, as well as some deprecated legacy functions that are also
13-strings.  See the module :mod:`re` for string functions based on regular
12+available as methods on strings. In addition, Python's built-in string
14-expressions.
13+classes support the sequence type methods described in the
14+:ref:`typesseq` section, and also the string-specific methods described
15+in the :ref:`string-methods` section. To output formatted strings use
16+template strings or the ``%`` operator described in the
17+:ref:`string-formatting` section. Also, see the :mod:`re` module for
18+string functions based on regular expressions.
15
16
17String constants
18----------------
19
20The constants defined in this module are:
21
22
53   The concatenation of the strings :const:`lowercase` and :const:`uppercase`
54   described below.  The specific value is locale-dependent, and will be updated
55   when :func:`locale.setlocale` is called.
56
57
58.. data:: lowercase
59
60   A string containing all the characters that are considered lowercase letters.
n61-   On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``.  Do not
n65+   On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``.  The
62-   change its definition --- the effect on the routines :func:`upper` and
66+   specific value is locale-dependent, and will be updated when
63-   :func:`swapcase` is undefined.  The specific value is locale-dependent, and will
64-   be updated when :func:`locale.setlocale` is called.
67+   :func:`locale.setlocale` is called.
65
66
67.. data:: octdigits
68
69   The string ``'01234567'``.
70
71
72.. data:: punctuation
80   String of characters which are considered printable.  This is a combination of
81   :const:`digits`, :const:`letters`, :const:`punctuation`, and
82   :const:`whitespace`.
83
84
85.. data:: uppercase
86
87   A string containing all the characters that are considered uppercase letters.
n88-   On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.  Do not
n91+   On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.  The
89-   change its definition --- the effect on the routines :func:`lower` and
92+   specific value is locale-dependent, and will be updated when
90-   :func:`swapcase` is undefined.  The specific value is locale-dependent, and will
91-   be updated when :func:`locale.setlocale` is called.
93+   :func:`locale.setlocale` is called.
92
93
94.. data:: whitespace
95
96   A string containing all characters that are considered whitespace. On most
97   systems this includes the characters space, tab, linefeed, return, formfeed, and
n98-   vertical tab.  Do not change its definition --- the effect on the routines
n100+   vertical tab.
99-   :func:`strip` and :func:`split` is undefined.
101+ 
102+ 
103+.. _new-string-formatting:
104+ 
105+String Formatting
106+-----------------
107+ 
108+Starting in Python 2.6, the built-in str and unicode classes provide the ability
109+to do complex variable substitutions and value formatting via the
110+:meth:`str.format` method described in :pep:`3101`.  The :class:`Formatter`
111+class in the :mod:`string` module allows you to create and customize your own
112+string formatting behaviors using the same implementation as the built-in
113+:meth:`format` method.
114+ 
115+.. class:: Formatter
116+ 
117+   The :class:`Formatter` class has the following public methods:
118+ 
119+   .. method:: format(format_string, *args, *kwargs)
120+ 
121+      :meth:`format` is the primary API method.  It takes a format template
122+      string, and an arbitrary set of positional and keyword argument.
123+      :meth:`format` is just a wrapper that calls :meth:`vformat`.
124+ 
125+   .. method:: vformat(format_string, args, kwargs)
126+ 
127+      This function does the actual work of formatting.  It is exposed as a
128+      separate function for cases where you want to pass in a predefined
129+      dictionary of arguments, rather than unpacking and repacking the
130+      dictionary as individual arguments using the ``*args`` and ``**kwds``
131+      syntax.  :meth:`vformat` does the work of breaking up the format template
132+      string into character data and replacement fields.  It calls the various
133+      methods described below.
134+ 
135+   In addition, the :class:`Formatter` defines a number of methods that are
136+   intended to be replaced by subclasses:
137+ 
138+   .. method:: parse(format_string)
139+ 
140+      Loop over the format_string and return an iterable of tuples
141+      (*literal_text*, *field_name*, *format_spec*, *conversion*).  This is used
142+      by :meth:`vformat` to break the string in to either literal text, or
143+      replacement fields.
144+ 
145+      The values in the tuple conceptually represent a span of literal text
146+      followed by a single replacement field.  If there is no literal text
147+      (which can happen if two replacement fields occur consecutively), then
148+      *literal_text* will be a zero-length string.  If there is no replacement
149+      field, then the values of *field_name*, *format_spec* and *conversion*
150+      will be ``None``.
151+ 
152+   .. method:: get_field(field_name, args, kwargs)
153+ 
154+      Given *field_name* as returned by :meth:`parse` (see above), convert it to
155+      an object to be formatted.  Returns a tuple (obj, used_key).  The default
156+      version takes strings of the form defined in :pep:`3101`, such as
157+      "0[name]" or "label.title".  *args* and *kwargs* are as passed in to
158+      :meth:`vformat`.  The return value *used_key* has the same meaning as the
159+      *key* parameter to :meth:`get_value`.
160+ 
161+   .. method:: get_value(key, args, kwargs)
162+ 
163+      Retrieve a given field value.  The *key* argument will be either an
164+      integer or a string.  If it is an integer, it represents the index of the
165+      positional argument in *args*; if it is a string, then it represents a
166+      named argument in *kwargs*.
167+ 
168+      The *args* parameter is set to the list of positional arguments to
169+      :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
170+      keyword arguments.
171+ 
172+      For compound field names, these functions are only called for the first
173+      component of the field name; Subsequent components are handled through
174+      normal attribute and indexing operations.
175+ 
176+      So for example, the field expression '0.name' would cause
177+      :meth:`get_value` to be called with a *key* argument of 0.  The ``name``
178+      attribute will be looked up after :meth:`get_value` returns by calling the
179+      built-in :func:`getattr` function.
180+ 
181+      If the index or keyword refers to an item that does not exist, then an
182+      :exc:`IndexError` or :exc:`KeyError` should be raised.
183+ 
184+   .. method:: check_unused_args(used_args, args, kwargs)
185+ 
186+      Implement checking for unused arguments if desired.  The arguments to this
187+      function is the set of all argument keys that were actually referred to in
188+      the format string (integers for positional arguments, and strings for
189+      named arguments), and a reference to the *args* and *kwargs* that was
190+      passed to vformat.  The set of unused args can be calculated from these
191+      parameters.  :meth:`check_unused_args` is assumed to throw an exception if
192+      the check fails.
193+ 
194+   .. method:: format_field(value, format_spec)
195+ 
196+      :meth:`format_field` simply calls the global :func:`format` built-in.  The
197+      method is provided so that subclasses can override it.
198+ 
199+   .. method:: convert_field(value, conversion)
200+ 
201+      Converts the value (returned by :meth:`get_field`) given a conversion type
202+      (as in the tuple returned by the :meth:`parse` method.)  The default
203+      version understands 'r' (repr) and 's' (str) conversion types.
204+ 
205+ 
206+.. _formatstrings:
207+ 
208+Format String Syntax
209+--------------------
210+ 
211+The :meth:`str.format` method and the :class:`Formatter` class share the same
212+syntax for format strings (although in the case of :class:`Formatter`,
213+subclasses can define their own format string syntax.)
214+ 
215+Format strings contain "replacement fields" surrounded by curly braces ``{}``.
216+Anything that is not contained in braces is considered literal text, which is
217+copied unchanged to the output.  If you need to include a brace character in the
218+literal text, it can be escaped by doubling: ``{{`` and ``}}``.
219+ 
220+The grammar for a replacement field is as follows:
221+ 
222+   .. productionlist:: sf
223+      replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
224+      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
225+      attribute_name: `identifier`
226+      element_index: `integer`
227+      conversion: "r" | "s"
228+      format_spec: <described in the next section>
229+ 
230+In less formal terms, the replacement field starts with a *field_name*, which
231+can either be a number (for a positional argument), or an identifier (for
232+keyword arguments).  Following this is an optional *conversion* field, which is
233+preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
234+by a colon ``':'``.
235+ 
236+The *field_name* itself begins with either a number or a keyword.  If it's a
237+number, it refers to a positional argument, and if it's a keyword it refers to a
238+named keyword argument.  This can be followed by any number of index or
239+attribute expressions. An expression of the form ``'.name'`` selects the named
240+attribute using :func:`getattr`, while an expression of the form ``'[index]'``
241+does an index lookup using :func:`__getitem__`.
242+ 
243+Some simple format string examples::
244+ 
245+   "First, thou shalt count to {0}" # References first positional argument
246+   "My quest is {name}"             # References keyword argument 'name'
247+   "Weight in tons {0.weight}"      # 'weight' attribute of first positional arg
248+   "Units destroyed: {players[0]}"  # First element of keyword argument 'players'.
249+ 
250+The *conversion* field causes a type coercion before formatting.  Normally, the
251+job of formatting a value is done by the :meth:`__format__` method of the value
252+itself.  However, in some cases it is desirable to force a type to be formatted
253+as a string, overriding its own definition of formatting.  By converting the
254+value to a string before calling :meth:`__format__`, the normal formatting logic
255+is bypassed.
256+ 
257+Two conversion flags are currently supported: ``'!s'`` which calls :func:`str`
258+on the value, and ``'!r'`` which calls :func:`repr`.
259+ 
260+Some examples::
261+ 
262+   "Harold's a clever {0!s}"        # Calls str() on the argument first
263+   "Bring out the holy {name!r}"    # Calls repr() on the argument first
264+ 
265+The *format_spec* field contains a specification of how the value should be
266+presented, including such details as field width, alignment, padding, decimal
267+precision and so on.  Each value type can define it's own "formatting
268+mini-language" or interpretation of the *format_spec*.
269+ 
270+Most built-in types support a common formatting mini-language, which is
271+described in the next section.
272+ 
273+A *format_spec* field can also include nested replacement fields within it.
274+These nested replacement fields can contain only a field name; conversion flags
275+and format specifications are not allowed.  The replacement fields within the
276+format_spec are substituted before the *format_spec* string is interpreted.
277+This allows the formatting of a value to be dynamically specified.
278+ 
279+For example, suppose you wanted to have a replacement field whose field width is
280+determined by another variable::
281+ 
282+   "A man with two {0:{1}}".format("noses", 10)
283+ 
284+This would first evaluate the inner replacement field, making the format string
285+effectively::
286+ 
287+   "A man with two {0:10}"
288+ 
289+Then the outer replacement field would be evaluated, producing::
290+ 
291+   "noses     "
292+ 
293+Which is substituted into the string, yielding::
294+ 
295+   "A man with two noses     "
296+ 
297+(The extra space is because we specified a field width of 10, and because left
298+alignment is the default for strings.)
299+ 
300+ 
301+.. _formatspec:
302+ 
303+Format Specification Mini-Language
304+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
305+ 
306+"Format specifications" are used within replacement fields contained within a
307+format string to define how individual values are presented (see
308+:ref:`formatstrings`.)  They can also be passed directly to the builtin
309+:func:`format` function.  Each formattable type may define how the format
310+specification is to be interpreted.
311+ 
312+Most built-in types implement the following options for format specifications,
313+although some of the formatting options are only supported by the numeric types.
314+ 
315+A general convention is that an empty format string (``""``) produces the same
316+result as if you had called :func:`str` on the value.
317+ 
318+The general form of a *standard format specifier* is:
319+ 
320+.. productionlist:: sf
321+   format_spec: [[`fill`]`align`][`sign`][#][0][`width`][.`precision`][`type`]
322+   fill: <a character other than '}'>
323+   align: "<" | ">" | "=" | "^"
324+   sign: "+" | "-" | " "
325+   width: `integer`
326+   precision: `integer`
327+   type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "x" | "X" | "%"
328+ 
329+The *fill* character can be any character other than '}' (which signifies the
330+end of the field).  The presence of a fill character is signaled by the *next*
331+character, which must be one of the alignment options. If the second character
332+of *format_spec* is not a valid alignment option, then it is assumed that both
333+the fill character and the alignment option are absent.
334+ 
335+The meaning of the various alignment options is as follows:
336+ 
337+   +---------+----------------------------------------------------------+
338+   | Option  | Meaning                                                  |
339+   +=========+==========================================================+
340+   | ``'<'`` | Forces the field to be left-aligned within the available |
341+   |         | space (This is the default.)                             |
342+   +---------+----------------------------------------------------------+
343+   | ``'>'`` | Forces the field to be right-aligned within the          |
344+   |         | available space.                                         |
345+   +---------+----------------------------------------------------------+
346+   | ``'='`` | Forces the padding to be placed after the sign (if any)  |
347+   |         | but before the digits.  This is used for printing fields |
348+   |         | in the form '+000000120'. This alignment option is only  |
349+   |         | valid for numeric types.                                 |
350+   +---------+----------------------------------------------------------+
351+   | ``'^'`` | Forces the field to be centered within the available     |
352+   |         | space.                                                   |
353+   +---------+----------------------------------------------------------+
354+ 
355+Note that unless a minimum field width is defined, the field width will always
356+be the same size as the data to fill it, so that the alignment option has no
357+meaning in this case.
358+ 
359+The *sign* option is only valid for number types, and can be one of the
360+following:
361+ 
362+   +---------+----------------------------------------------------------+
363+   | Option  | Meaning                                                  |
364+   +=========+==========================================================+
365+   | ``'+'`` | indicates that a sign should be used for both            |
366+   |         | positive as well as negative numbers.                    |
367+   +---------+----------------------------------------------------------+
368+   | ``'-'`` | indicates that a sign should be used only for negative   |
369+   |         | numbers (this is the default behavior).                  |
370+   +---------+----------------------------------------------------------+
371+   | space   | indicates that a leading space should be used on         |
372+   |         | positive numbers, and a minus sign on negative numbers.  |
373+   +---------+----------------------------------------------------------+
374+ 
375+The ``'#'`` option is only valid for integers, and only for binary, octal, or
376+hexadecimal output.  If present, it specifies that the output will be prefixed
377+by ``'0b'``, ``'0o'``, or ``'0x'``, respectively.
378+ 
379+*width* is a decimal integer defining the minimum field width.  If not
380+specified, then the field width will be determined by the content.
381+ 
382+If the *width* field is preceded by a zero (``'0'``) character, this enables
383+zero-padding.  This is equivalent to an *alignment* type of ``'='`` and a *fill*
384+character of ``'0'``.
385+ 
386+The *precision* is a decimal number indicating how many digits should be
387+displayed after the decimal point for a floating point value formatted with
388+``'f'`` and ``'F'``, or before and after the decimal point for a floating point
389+value formatted with ``'g'`` or ``'G'``.  For non-number types the field
390+indicates the maximum field size - in other words, how many characters will be
391+used from the field content. The *precision* is ignored for integer values.
392+ 
393+Finally, the *type* determines how the data should be presented.
394+ 
395+The available integer presentation types are:
396+ 
397+   +---------+----------------------------------------------------------+
398+   | Type    | Meaning                                                  |
399+   +=========+==========================================================+
400+   | ``'b'`` | Binary format. Outputs the number in base 2.             |
401+   +---------+----------------------------------------------------------+
402+   | ``'c'`` | Character. Converts the integer to the corresponding     |
403+   |         | unicode character before printing.                       |
404+   +---------+----------------------------------------------------------+
405+   | ``'d'`` | Decimal Integer. Outputs the number in base 10.          |
406+   +---------+----------------------------------------------------------+
407+   | ``'o'`` | Octal format. Outputs the number in base 8.              |
408+   +---------+----------------------------------------------------------+
409+   | ``'x'`` | Hex format. Outputs the number in base 16, using lower-  |
410+   |         | case letters for the digits above 9.                     |
411+   +---------+----------------------------------------------------------+
412+   | ``'X'`` | Hex format. Outputs the number in base 16, using upper-  |
413+   |         | case letters for the digits above 9.                     |
414+   +---------+----------------------------------------------------------+
415+   | ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
416+   |         | the current locale setting to insert the appropriate     |
417+   |         | number separator characters.                             |
418+   +---------+----------------------------------------------------------+
419+   | None    | The same as ``'d'``.                                     |
420+   +---------+----------------------------------------------------------+
421+ 
422+The available presentation types for floating point and decimal values are:
423+ 
424+   +---------+----------------------------------------------------------+
425+   | Type    | Meaning                                                  |
426+   +=========+==========================================================+
427+   | ``'e'`` | Exponent notation. Prints the number in scientific       |
428+   |         | notation using the letter 'e' to indicate the exponent.  |
429+   +---------+----------------------------------------------------------+
430+   | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an     |
431+   |         | upper case 'E' as the separator character.               |
432+   +---------+----------------------------------------------------------+
433+   | ``'f'`` | Fixed point. Displays the number as a fixed-point        |
434+   |         | number.                                                  |
435+   +---------+----------------------------------------------------------+
436+   | ``'F'`` | Fixed point. Same as ``'f'``.                            |
437+   +---------+----------------------------------------------------------+
438+   | ``'g'`` | General format. This prints the number as a fixed-point  |
439+   |         | number, unless the number is too large, in which case    |
440+   |         | it switches to ``'e'`` exponent notation. Infinity and   |
441+   |         | NaN values are formatted as ``inf``, ``-inf`` and        |
442+   |         | ``nan``, respectively.                                   |
443+   +---------+----------------------------------------------------------+
444+   | ``'G'`` | General format. Same as ``'g'`` except switches to       |
445+   |         | ``'E'`` if the number gets to large. The representations |
446+   |         | of infinity and NaN are uppercased, too.                 |
447+   +---------+----------------------------------------------------------+
448+   | ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
449+   |         | the current locale setting to insert the appropriate     |
450+   |         | number separator characters.                             |
451+   +---------+----------------------------------------------------------+
452+   | ``'%'`` | Percentage. Multiplies the number by 100 and displays    |
453+   |         | in fixed (``'f'``) format, followed by a percent sign.   |
454+   +---------+----------------------------------------------------------+
455+   | None    | The same as ``'g'``.                                     |
456+   +---------+----------------------------------------------------------+
100
101
102Template strings
103----------------
104
105Templates provide simpler string substitutions as described in :pep:`292`.
106Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
107-based substitutions, using the following rules:
108
109* ``$$`` is an escape; it is replaced with a single ``$``.
110
111* ``$identifier`` names a substitution placeholder matching a mapping key of
n112-  "identifier".  By default, "identifier" must spell a Python identifier.  The
n469+  ``"identifier"``.  By default, ``"identifier"`` must spell a Python
113-  first non-identifier character after the ``$`` character terminates this
470+  identifier.  The first non-identifier character after the ``$`` character
114-  placeholder specification.
471+  terminates this placeholder specification.
115
116* ``${identifier}`` is equivalent to ``$identifier``.  It is required when valid
117  identifier characters follow the placeholder but are not part of the
n118-  placeholder, such as "${noun}ification".
n475+  placeholder, such as ``"${noun}ification"``.
119
120Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
121being raised.
122
123.. versionadded:: 2.4
124
125The :mod:`string` module provides a :class:`Template` class that implements
126these rules.  The methods of :class:`Template` are:
127
128
129.. class:: Template(template)
130
131   The constructor takes a single argument which is the template string.
132
133
n134-.. method:: Template.substitute(mapping[, **kws])
n491+   .. method:: substitute(mapping[, **kws])
135
n136-   Performs the template substitution, returning a new string.  *mapping* is any
n493+      Performs the template substitution, returning a new string.  *mapping* is
137-   dictionary-like object with keys that match the placeholders in the template.
494+      any dictionary-like object with keys that match the placeholders in the
138-   Alternatively, you can provide keyword arguments, where the keywords are the
495+      template.  Alternatively, you can provide keyword arguments, where the
139-   placeholders.  When both *mapping* and *kws* are given and there are duplicates,
496+      keywords are the placeholders.  When both *mapping* and *kws* are given
140-   the placeholders from *kws* take precedence.
497+      and there are duplicates, the placeholders from *kws* take precedence.
141
142
n143-.. method:: Template.safe_substitute(mapping[, **kws])
n500+   .. method:: safe_substitute(mapping[, **kws])
144
n145-   Like :meth:`substitute`, except that if placeholders are missing from *mapping*
n502+      Like :meth:`substitute`, except that if placeholders are missing from
146-   and *kws*, instead of raising a :exc:`KeyError` exception, the original
503+      *mapping* and *kws*, instead of raising a :exc:`KeyError` exception, the
147-   placeholder will appear in the resulting string intact.  Also, unlike with
504+      original placeholder will appear in the resulting string intact.  Also,
148-   :meth:`substitute`, any other appearances of the ``$`` will simply return ``$``
505+      unlike with :meth:`substitute`, any other appearances of the ``$`` will
149-   instead of raising :exc:`ValueError`.
506+      simply return ``$`` instead of raising :exc:`ValueError`.
150
n151-   While other exceptions may still occur, this method is called "safe" because
n508+      While other exceptions may still occur, this method is called "safe"
152-   substitutions always tries to return a usable string instead of raising an
509+      because substitutions always tries to return a usable string instead of
153-   exception.  In another sense, :meth:`safe_substitute` may be anything other than
510+      raising an exception.  In another sense, :meth:`safe_substitute` may be
154-   safe, since it will silently ignore malformed templates containing dangling
511+      anything other than safe, since it will silently ignore malformed
155-   delimiters, unmatched braces, or placeholders that are not valid Python
512+      templates containing dangling delimiters, unmatched braces, or
156-   identifiers.
513+      placeholders that are not valid Python identifiers.
157
158:class:`Template` instances also provide one public data attribute:
159
160
161.. attribute:: string.template
162
163   This is the object passed to the constructor's *template* argument.  In general,
164   you shouldn't change it, but read-only access is not enforced.
165
n166-Here is an example of how to use a Template::
n523+Here is an example of how to use a Template:
167
168   >>> from string import Template
169   >>> s = Template('$who likes $what')
170   >>> s.substitute(who='tim', what='kung pao')
171   'tim likes kung pao'
172   >>> d = dict(who='tim')
173   >>> Template('Give $who $100').substitute(d)
174   Traceback (most recent call last):
185placeholder syntax, delimiter character, or the entire regular expression used
186to parse template strings.  To do this, you can override these class attributes:
187
188* *delimiter* -- This is the literal string describing a placeholder introducing
189  delimiter.  The default value ``$``.  Note that this should *not* be a regular
190  expression, as the implementation will call :meth:`re.escape` on this string as
191  needed.
192
n193-* *idpattern* -- This is the regular expression describing the pattern for non-
n550+* *idpattern* -- This is the regular expression describing the pattern for
194-  braced placeholders (the braces will be added automatically as appropriate).
551+  non-braced placeholders (the braces will be added automatically as
195-  The default value is the regular expression ``[_a-z][_a-z0-9]*``.
552+  appropriate).  The default value is the regular expression
553+  ``[_a-z][_a-z0-9]*``.
196
197Alternatively, you can provide the entire regular expression pattern by
198overriding the class attribute *pattern*.  If you do this, the value must be a
199regular expression object with four named capturing groups.  The capturing
200groups correspond to the rules given above, along with the invalid placeholder
201rule:
202
203* *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the
225   Split the argument into words using :func:`split`, capitalize each word using
226   :func:`capitalize`, and join the capitalized words using :func:`join`.  Note
227   that this replaces runs of whitespace characters by a single space, and removes
228   leading and trailing whitespace.
229
230
231.. function:: maketrans(from, to)
232
n233-   Return a translation table suitable for passing to :func:`translate` or
n591+   Return a translation table suitable for passing to :func:`translate`, that will
234-   :func:`regex.compile`, that will map each character in *from* into the character
592+   map each character in *from* into the character at the same position in *to*;
235-   at the same position in *to*; *from* and *to* must have the same length.
593+   *from* and *to* must have the same length.
236
237   .. warning::
238
239      Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
240      arguments; in some locales, these don't have the same length.  For case
n241-      conversions, always use :func:`lower` and :func:`upper`.
n599+      conversions, always use :meth:`str.lower` and :meth:`str.upper`.
242
243
244Deprecated string functions
245---------------------------
246
247The following list of functions are also defined as methods of string and
n248-Unicode objects; see "String Methods" (section :ref:`string-methods`) for more
n606+Unicode objects; see section :ref:`string-methods` for more information on
249-information on those.  You should consider these functions as deprecated,
607+those.  You should consider these functions as deprecated, although they will
250-although they will not be removed until Python 3.0.  The functions defined in
608+not be removed until Python 3.0.  The functions defined in this module are:
251-this module are:
252
253
254.. function:: atof(s)
255
256   .. deprecated:: 2.0
257      Use the :func:`float` built-in function.
258
259   .. index:: builtin: float
451   Return a copy of *s*, but with lower case letters converted to upper case and
452   vice versa.
453
454
455.. function:: translate(s, table[, deletechars])
456
457   Delete all characters from *s* that are in *deletechars* (if  present), and then
458   translate the characters using *table*, which  must be a 256-character string
t459-   giving the translation for each character value, indexed by its ordinal.
t816+   giving the translation for each character value, indexed by its ordinal.  If
817+   *table* is ``None``, then only the character deletion step is performed.
460
461
462.. function:: upper(s)
463
464   Return a copy of *s*, but with lower case letters converted to upper case.
465
466
467.. function:: ljust(s, width)
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op