[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / node109.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node110.html" />
<link rel="prev" href="node108.html" />
<link rel="parent" href="module-string.html" />
<link rel="next" href="node110.html" />
<meta name='aesop' content='information' />
<title>4.1.2 Template strings</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.1.1 String constants"
  href="node108.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.1 string  "
  href="module-string.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.1.3 String functions"
  href="node110.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node108.html">4.1.1 String constants</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-string.html">4.1 string  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node110.html">4.1.3 String functions</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION006120000000000000000">
4.1.2 Template strings</A>
</H2>

<P>
Templates provide simpler string substitutions as described in <a class="rfc" id='rfcref-86823' xml:id='rfcref-86823'
href="http://www.python.org/peps/pep-0292.html">PEP 292</a>.
Instead of the normal "<tt class="samp">%</tt>"-based substitutions, Templates support
"<tt class="samp">$</tt>"-based substitutions, using the following rules:

<P>

<UL>
<LI>"<tt class="samp">$$</tt>" is an escape; it is replaced with a single "<tt class="samp">$</tt>".

<P>
</LI>
<LI>"<tt class="samp">$identifier</tt>" names a substitution placeholder matching a mapping
       key of "identifier".  By default, "identifier" must spell a Python
       identifier.  The first non-identifier character after the "<tt class="samp">$</tt>"       character terminates this placeholder specification.

<P>
</LI>
<LI>"<tt class="samp">${identifier}</tt>" is equivalent to "<tt class="samp">$identifier</tt>".  It is
      required when valid identifier characters follow the placeholder but are
      not part of the placeholder, such as "${noun}ification".
</LI>
</UL>

<P>
Any other appearance of "<tt class="samp">$</tt>" in the string will result in a
<tt class="exception">ValueError</tt> being raised.

<P>

<span class="versionnote">New in version 2.4.</span>

<P>
The <tt class="module">string</tt> module provides a <tt class="class">Template</tt> class that implements
these rules.  The methods of <tt class="class">Template</tt> are:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-830' xml:id='l2h-830' class="class">Template</tt></b>(</nobr></td>
  <td><var>template</var>)</td></tr></table></dt>
<dd>
The constructor takes a single argument which is the template string.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-831' xml:id='l2h-831' class="method">substitute</tt></b>(</nobr></td>
  <td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Performs the template substitution, returning a new string.  <var>mapping</var> is
any dictionary-like object with keys that match the placeholders in the
template.  Alternatively, you can provide keyword arguments, where the
keywords are the placeholders.  When both <var>mapping</var> and <var>kws</var> are
given and there are duplicates, the placeholders from <var>kws</var> take
precedence.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-832' xml:id='l2h-832' class="method">safe_substitute</tt></b>(</nobr></td>
  <td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Like <tt class="method">substitute()</tt>, except that if placeholders are missing from
<var>mapping</var> and <var>kws</var>, instead of raising a <tt class="exception">KeyError</tt>
exception, the original placeholder will appear in the resulting string
intact.  Also, unlike with <tt class="method">substitute()</tt>, any other appearances of the
"<tt class="samp">$</tt>" will simply return "<tt class="samp">$</tt>" instead of raising
<tt class="exception">ValueError</tt>.

<P>
While other exceptions may still occur, this method is called ``safe'' because
substitutions always tries to return a usable string instead of raising an
exception.  In another sense, <tt class="method">safe_substitute()</tt> may be anything other
than safe, since it will silently ignore malformed templates containing
dangling delimiters, unmatched braces, or placeholders that are not valid
Python identifiers.
</dl>

<P>
<tt class="class">Template</tt> instances also provide one public data attribute:

<P>
<dl><dt><b><tt id='l2h-833' xml:id='l2h-833' class="member">template</tt></b></dt>
<dd>
This is the object passed to the constructor's <var>template</var> argument.  In
general, you shouldn't change it, but read-only access is not enforced.
</dl>

<P>
Here is an example of how to use a Template:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; from string import Template
&gt;&gt;&gt; s = Template('$who likes $what')
&gt;&gt;&gt; s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
&gt;&gt;&gt; d = dict(who='tim')
&gt;&gt;&gt; Template('Give $who $100').substitute(d)
Traceback (most recent call last):
[...]
ValueError: Invalid placeholder in string: line 1, col 10
&gt;&gt;&gt; Template('$who likes $what').substitute(d)
Traceback (most recent call last):
[...]
KeyError: 'what'
&gt;&gt;&gt; Template('$who likes $what').safe_substitute(d)
'tim likes $what'
</pre></div>

<P>
Advanced usage: you can derive subclasses of <tt class="class">Template</tt> to customize the
placeholder syntax, delimiter character, or the entire regular expression used
to parse template strings.  To do this, you can override these class
attributes:

<P>

<UL>
<LI><var>delimiter</var> - This is the literal string describing a placeholder
      introducing delimiter.  The default value "<tt class="samp">$</tt>".  Note that this
      should <em>not</em> be a regular expression, as the implementation will
      call <tt class="method">re.escape()</tt> on this string as needed.
</LI>
<LI><var>idpattern</var> - This is the regular expression describing the pattern
      for non-braced placeholders (the braces will be added automatically as
      appropriate).  The default value is the regular expression
      "<tt class="samp">[_a-z][_a-z0-9]*</tt>".
</LI>
</UL>

<P>
Alternatively, you can provide the entire regular expression pattern by
overriding the class attribute <var>pattern</var>.  If you do this, the value must
be a regular expression object with four named capturing groups.  The
capturing groups correspond to the rules given above, along with the invalid
placeholder rule:

<P>

<UL>
<LI><var>escaped</var> - This group matches the escape sequence,
      e.g. "<tt class="samp">$$</tt>", in the default pattern.
</LI>
<LI><var>named</var> - This group matches the unbraced placeholder name; it
      should not include the delimiter in capturing group.
</LI>
<LI><var>braced</var> - This group matches the brace enclosed placeholder name;
      it should not include either the delimiter or braces in the capturing
      group.
</LI>
<LI><var>invalid</var> - This group matches any other delimiter pattern (usually
      a single delimiter), and it should appear last in the regular
      expression.
</LI>
</UL>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.1.1 String constants"
  href="node108.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.1 string  "
  href="module-string.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.1.3 String functions"
  href="node110.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node108.html">4.1.1 String constants</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-string.html">4.1 string  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node110.html">4.1.3 String functions</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="node110.html" />
	13	<link rel="prev" href="node108.html" />
	14	<link rel="parent" href="module-string.html" />
	15	<link rel="next" href="node110.html" />
	16	<meta name='aesop' content='information' />
	17	<title>4.1.2 Template strings</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="4.1.1 String constants"
	25	href="node108.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="4.1 string "
	28	href="module-string.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="4.1.3 String functions"
	31	href="node110.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="node108.html">4.1.1 String constants</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-string.html">4.1 string </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="node110.html">4.1.3 String functions</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION006120000000000000000">
	56	4.1.2 Template strings</A>
	57	</H2>
	58
	59	<P>
	60	Templates provide simpler string substitutions as described in <a class="rfc" id='rfcref-86823' xml:id='rfcref-86823'
	61	href="http://www.python.org/peps/pep-0292.html">PEP 292</a>.
	62	Instead of the normal "<tt class="samp">%</tt>"-based substitutions, Templates support
	63	"<tt class="samp">$</tt>"-based substitutions, using the following rules:
	64
65	<P>
66
67	<UL>
68	<LI>"<tt class="samp">$$</tt>" is an escape; it is replaced with a single "<tt class="samp">$</tt>".
69
70	<P>
71	</LI>
72	<LI>"<tt class="samp">$identifier</tt>" names a substitution placeholder matching a mapping
73	key of "identifier". By default, "identifier" must spell a Python
74	identifier. The first non-identifier character after the "<tt class="samp">$</tt>" character terminates this placeholder specification.
75
76	<P>
77	</LI>
78	<LI>"<tt class="samp">${identifier}</tt>" is equivalent to "<tt class="samp">$identifier</tt>". It is
79	required when valid identifier characters follow the placeholder but are
80	not part of the placeholder, such as "${noun}ification".
81	</LI>
82	</UL>
83
84	<P>
85	Any other appearance of "<tt class="samp">$</tt>" in the string will result in a
86	<tt class="exception">ValueError</tt> being raised.
87
88	<P>
89
90	<span class="versionnote">New in version 2.4.</span>
91
92	<P>
93	The <tt class="module">string</tt> module provides a <tt class="class">Template</tt> class that implements
94	these rules. The methods of <tt class="class">Template</tt> are:
95
96	<P>
97	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
98	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-830' xml:id='l2h-830' class="class">Template</tt></b>(</nobr></td>
99	<td><var>template</var>)</td></tr></table></dt>
100	<dd>
101	The constructor takes a single argument which is the template string.
102	</dl>
103
104	<P>
105	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
106	<td><nobr><b><tt id='l2h-831' xml:id='l2h-831' class="method">substitute</tt></b>(</nobr></td>
107	<td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
108	<dd>
109	Performs the template substitution, returning a new string. <var>mapping</var> is
110	any dictionary-like object with keys that match the placeholders in the
111	template. Alternatively, you can provide keyword arguments, where the
112	keywords are the placeholders. When both <var>mapping</var> and <var>kws</var> are
113	given and there are duplicates, the placeholders from <var>kws</var> take
114	precedence.
115	</dl>
116
117	<P>
118	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
119	<td><nobr><b><tt id='l2h-832' xml:id='l2h-832' class="method">safe_substitute</tt></b>(</nobr></td>
120	<td><var>mapping</var><big>[</big><var>, **kws</var><big>]</big><var></var>)</td></tr></table></dt>
121	<dd>
122	Like <tt class="method">substitute()</tt>, except that if placeholders are missing from
123	<var>mapping</var> and <var>kws</var>, instead of raising a <tt class="exception">KeyError</tt>
124	exception, the original placeholder will appear in the resulting string
125	intact. Also, unlike with <tt class="method">substitute()</tt>, any other appearances of the
126	"<tt class="samp">$</tt>" will simply return "<tt class="samp">$</tt>" instead of raising
127	<tt class="exception">ValueError</tt>.
128
129	<P>
130	While other exceptions may still occur, this method is called ``safe'' because
131	substitutions always tries to return a usable string instead of raising an
132	exception. In another sense, <tt class="method">safe_substitute()</tt> may be anything other
133	than safe, since it will silently ignore malformed templates containing
134	dangling delimiters, unmatched braces, or placeholders that are not valid
135	Python identifiers.
136	</dl>
137
138	<P>
139	<tt class="class">Template</tt> instances also provide one public data attribute:
140
141	<P>
142	<dl><dt><b><tt id='l2h-833' xml:id='l2h-833' class="member">template</tt></b></dt>
143	<dd>
144	This is the object passed to the constructor's <var>template</var> argument. In
145	general, you shouldn't change it, but read-only access is not enforced.
146	</dl>
147
148	<P>
149	Here is an example of how to use a Template:
150
151	<P>
152	<div class="verbatim"><pre>
153	>>> from string import Template
154	>>> s = Template('$who likes $what')
155	>>> s.substitute(who='tim', what='kung pao')
156	'tim likes kung pao'
157	>>> d = dict(who='tim')
158	>>> Template('Give $who $100').substitute(d)
159	Traceback (most recent call last):
160	[...]
161	ValueError: Invalid placeholder in string: line 1, col 10
162	>>> Template('$who likes $what').substitute(d)
163	Traceback (most recent call last):
164	[...]
165	KeyError: 'what'
166	>>> Template('$who likes $what').safe_substitute(d)
167	'tim likes $what'
168	</pre></div>
169
170	<P>
171	Advanced usage: you can derive subclasses of <tt class="class">Template</tt> to customize the
172	placeholder syntax, delimiter character, or the entire regular expression used
173	to parse template strings. To do this, you can override these class
174	attributes:
175
176	<P>
177
178	<UL>
179	<LI><var>delimiter</var> - This is the literal string describing a placeholder
180	introducing delimiter. The default value "<tt class="samp">$</tt>". Note that this
181	should <em>not</em> be a regular expression, as the implementation will
182	call <tt class="method">re.escape()</tt> on this string as needed.
183	</LI>
184	<LI><var>idpattern</var> - This is the regular expression describing the pattern
185	for non-braced placeholders (the braces will be added automatically as
186	appropriate). The default value is the regular expression
187	"<tt class="samp">[_a-z][_a-z0-9]*</tt>".
188	</LI>
189	</UL>
190
191	<P>
192	Alternatively, you can provide the entire regular expression pattern by
193	overriding the class attribute <var>pattern</var>. If you do this, the value must
194	be a regular expression object with four named capturing groups. The
195	capturing groups correspond to the rules given above, along with the invalid
196	placeholder rule:
197
198	<P>
199
200	<UL>
201	<LI><var>escaped</var> - This group matches the escape sequence,
202	e.g. "<tt class="samp">$$</tt>", in the default pattern.
203	</LI>
204	<LI><var>named</var> - This group matches the unbraced placeholder name; it
205	should not include the delimiter in capturing group.
206	</LI>
207	<LI><var>braced</var> - This group matches the brace enclosed placeholder name;
208	it should not include either the delimiter or braces in the capturing
209	group.
210	</LI>
211	<LI><var>invalid</var> - This group matches any other delimiter pattern (usually
212	a single delimiter), and it should appear last in the regular
213	expression.
214	</LI>
215	</UL>
216
217	<P>
218
219	<DIV CLASS="navigation">
220	<div class='online-navigation'>
221	<p></p><hr />
222	<table align="center" width="100%" cellpadding="0" cellspacing="2">
223	<tr>
224	<td class='online-navigation'><a rel="prev" title="4.1.1 String constants"
225	href="node108.html"><img src='../icons/previous.png'
226	border='0' height='32' alt='Previous Page' width='32' /></A></td>
227	<td class='online-navigation'><a rel="parent" title="4.1 string "
228	href="module-string.html"><img src='../icons/up.png'
229	border='0' height='32' alt='Up One Level' width='32' /></A></td>
230	<td class='online-navigation'><a rel="next" title="4.1.3 String functions"
231	href="node110.html"><img src='../icons/next.png'
232	border='0' height='32' alt='Next Page' width='32' /></A></td>
233	<td align="center" width="100%">Python Library Reference</td>
234	<td class='online-navigation'><a rel="contents" title="Table of Contents"
235	href="contents.html"><img src='../icons/contents.png'
236	border='0' height='32' alt='Contents' width='32' /></A></td>
237	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
238	border='0' height='32' alt='Module Index' width='32' /></a></td>
239	<td class='online-navigation'><a rel="index" title="Index"
240	href="genindex.html"><img src='../icons/index.png'
241	border='0' height='32' alt='Index' width='32' /></A></td>
242	</tr></table>
243	<div class='online-navigation'>
244	<b class="navlabel">Previous:</b>
245	<a class="sectref" rel="prev" href="node108.html">4.1.1 String constants</A>
246	<b class="navlabel">Up:</b>
247	<a class="sectref" rel="parent" href="module-string.html">4.1 string </A>
248	<b class="navlabel">Next:</b>
249	<a class="sectref" rel="next" href="node110.html">4.1.3 String functions</A>
250	</div>
251	</div>
252	<hr />
253	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
254	</DIV>
255	<!--End of Navigation Panel-->
256	<ADDRESS>
257	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
258	</ADDRESS>
259	</BODY>
260	</HTML>