@@ -4,11 +4,23 @@ \section{\module{string} ---
44\declaremodule {standard}{string}
55\modulesynopsis {Common string operations.}
66
7+ The \module {string} package contains a number of useful constants and classes,
8+ as well as some deprecated legacy functions that are also available as methods
9+ on strings. See the module \refmodule {re}\refstmodindex {re} for string
10+ functions based on regular expressions.
711
8- This module defines some constants useful for checking character
9- classes and some useful string functions. See the module
10- \refmodule {re}\refstmodindex {re} for string functions based on regular
11- expressions.
12+ In general, all of these objects are exposed directly in the \module {string}
13+ package so users need only import the \module {string} package to begin using
14+ these constants, classes, and functions.
15+
16+ \begin {notice }
17+ Starting with Python 2.4, the traditional \module {string} module was turned
18+ into a package, however backward compatibility with existing code has been
19+ retained. Code using the \module {string} module that worked prior to Python
20+ 2.4 should continue to work unchanged.
21+ \end {notice }
22+
23+ \subsection {String constants }
1224
1325The constants defined in this module are:
1426
@@ -86,11 +98,113 @@ \section{\module{string} ---
8698 is undefined.
8799\end {datadesc }
88100
101+ \subsection {Template strings }
102+
103+ Templates are Unicode strings that can be used to provide string substitutions
104+ as described in \pep {292}. There is a \class {Template} class that is a
105+ subclass of \class {unicode}, overriding the default \method {__mod__()} method.
106+ Instead of the normal \samp {\% }-based substitutions, Template strings support
107+ \samp {\$ }-based substitutions, using the following rules:
108+
109+ \begin {itemize }
110+ \item \samp {\$\$ } is an escape; it is replaced with a single \samp {\$ }.
111+
112+ \item \samp {\$ identifier} names a substitution placeholder matching a mapping
113+ key of "identifier" . By default, "identifier" must spell a Python
114+ identifier. The first non-identifier character after the \samp {\$ }
115+ character terminates this placeholder specification.
116+
117+ \item \samp {\$\{ identifier\} } is equivalent to \samp {\$ identifier}. It is
118+ required when valid identifier characters follow the placeholder but are
119+ not part of the placeholder, e.g. "\$\{noun\}ification" .
120+ \end {itemize }
121+
122+ Any other appearance of \samp {\$ } in the string will result in a
123+ \exception {ValueError} being raised.
124+
125+ Template strings are used just like normal strings, in that the modulus
126+ operator is used to interpolate a dictionary of values into a Template string,
127+ e.g.:
128+
129+ \begin {verbatim }
130+ >>> from string import Template
131+ >>> s = Template('$who likes $what')
132+ >>> print s % dict(who='tim', what='kung pao')
133+ tim likes kung pao
134+ >>> Template('Give $who $100') % dict(who='tim')
135+ Traceback (most recent call last):
136+ [...]
137+ ValueError: Invalid placeholder at index 10
138+ \end {verbatim }
139+
140+ There is also a \class {SafeTemplate} class, derived from \class {Template}
141+ which acts the same as \class {Template}, except that if placeholders are
142+ missing in the interpolation dictionary, no \exception {KeyError} will be
143+ raised. Instead the original placeholder (with or without the braces, as
144+ appropriate) will be used:
145+
146+ \begin {verbatim }
147+ >>> from string import SafeTemplate
148+ >>> s = SafeTemplate('$who likes $what for ${meal}')
149+ >>> print s % dict(who='tim')
150+ tim likes $what for ${meal}
151+ \end {verbatim }
152+
153+ The values in the mapping will automatically be converted to Unicode strings,
154+ using the built-in \function {unicode()} function, which will be called without
155+ optional arguments \var {encoding} or \var {errors}.
156+
157+ Advanced usage: you can derive subclasses of \class {Template} or
158+ \class {SafeTemplate} to use application-specific placeholder rules. To do
159+ this, you override the class attribute \member {pattern}; the value must be a
160+ compiled regular expression object with four named capturing groups. The
161+ capturing groups correspond to the rules given above, along with the invalid
162+ placeholder rule:
163+
164+ \begin {itemize }
165+ \item \var {escaped} -- This group matches the escape sequence, i.e. \samp {\$\$ }
166+ in the default pattern.
167+ \item \var {named} -- This group matches the unbraced placeholder name; it
168+ should not include the \samp {\$ } in capturing group.
169+ \item \var {braced} -- This group matches the brace delimited placeholder name;
170+ it should not include either the \samp {\$ } or braces in the capturing
171+ group.
172+ \item \var {bogus} -- This group matches any other \samp {\$ }. It usually just
173+ matches a single \samp {\$ } and should appear last.
174+ \end {itemize }
175+
176+ \subsection {String functions }
177+
178+ The following functions are available to operate on string and Unicode
179+ objects. They are not available as string methods.
180+
181+ \begin {funcdesc }{capwords}{s}
182+ Split the argument into words using \function {split()}, capitalize
183+ each word using \function {capitalize()}, and join the capitalized
184+ words using \function {join()}. Note that this replaces runs of
185+ whitespace characters by a single space, and removes leading and
186+ trailing whitespace.
187+ \end {funcdesc }
188+
189+ \begin {funcdesc }{maketrans}{from, to}
190+ Return a translation table suitable for passing to
191+ \function {translate()} or \function {regex.compile()}, that will map
192+ each character in \var {from} into the character at the same position
193+ in \var {to}; \var {from} and \var {to} must have the same length.
194+
195+ \warning {Don't use strings derived from \constant {lowercase}
196+ and \constant {uppercase} as arguments; in some locales, these don't have
197+ the same length. For case conversions, always use
198+ \function {lower()} and \function {upper()}.}
199+ \end {funcdesc }
89200
90- Many of the functions provided by this module are also defined as
91- methods of string and Unicode objects; see `` String Methods''
92- \ref {string-methods }) for more information on those.
93- The functions defined in this module are:
201+ \subsection {Deprecated string functions }
202+
203+ The following list of functions are also defined as methods of string and
204+ Unicode objects; see `` String Methods''
205+ \ref {string-methods }) for more information on those. You should consider
206+ these functions as deprecated, although they will not be removed until Python
207+ 3.0. The functions defined in this module are:
94208
95209\begin {funcdesc }{atof}{s}
96210 \deprecated {2.0}{Use the \function {float()} built-in function.}
@@ -138,14 +252,6 @@ \section{\module{string} ---
138252 Return a copy of \var {word} with only its first character capitalized.
139253\end {funcdesc }
140254
141- \begin {funcdesc }{capwords}{s}
142- Split the argument into words using \function {split()}, capitalize
143- each word using \function {capitalize()}, and join the capitalized
144- words using \function {join()}. Note that this replaces runs of
145- whitespace characters by a single space, and removes leading and
146- trailing whitespace.
147- \end {funcdesc }
148-
149255\begin {funcdesc }{expandtabs}{s\optional {, tabsize}}
150256 Expand tabs in a string, i.e.\ replace them by one or more spaces,
151257 depending on the current column and the given tab size. The column
@@ -188,18 +294,6 @@ \section{\module{string} ---
188294 lower case.
189295\end {funcdesc }
190296
191- \begin {funcdesc }{maketrans}{from, to}
192- Return a translation table suitable for passing to
193- \function {translate()} or \function {regex.compile()}, that will map
194- each character in \var {from} into the character at the same position
195- in \var {to}; \var {from} and \var {to} must have the same length.
196-
197- \warning {Don't use strings derived from \constant {lowercase}
198- and \constant {uppercase} as arguments; in some locales, these don't have
199- the same length. For case conversions, always use
200- \function {lower()} and \function {upper()}.}
201- \end {funcdesc }
202-
203297\begin {funcdesc }{split}{s\optional {, sep\optional {, maxsplit}}}
204298 Return a list of the words of the string \var {s}. If the optional
205299 second argument \var {sep} is absent or \code {None}, the words are
0 commit comments