Updated and simplified PEP, after a few very good rounds of discussion with

Raymond.

pep-0292.txt

@@ -43,11 +43,11 @@ Rationale
 
 A Simpler Proposal
 
-    We propose the addition of a new class -- called 'dstring' --
-    derived from the built-in unicode type, which supports new rules
-    for string substitution.  dstring's value contains placeholders,
-    introduced with the $ character.  The following rules for
-    $-placeholders apply:
+    We propose the addition of a new class -- called 'template', which
+    will live in the string module -- derived from the built-in
+    unicode type.  The template class supports new rules for string
+    substitution; its value contains placeholders, introduced with the
+    $ character.  The following rules for $-placeholders apply:
 
     1. $$ is an escape; it is replaced with a single $
 
@@ -57,7 +57,7 @@ A Simpler Proposal
        character after the $ character terminates this placeholder
        specification.
 
-    3. ${identifier} is equivalent to $identifier.  It is required for
+    3. ${identifier} is equivalent to $identifier.  It is required
        when valid identifier characters follow the placeholder but are
        not part of the placeholder, e.g. "${noun}ification".
 
@@ -67,19 +67,39 @@ A Simpler Proposal
     unchanged.
 
     No other characters have special meaning, however it is possible
-    to derive from the dstring class to define different rules for the
-    placeholder.  For example, a derived class could allow for periods
-    in the placeholder (e.g. to support a kind of dynamic namespace
-    and attribute path lookup).
+    to derive from the template class to define different rules for
+    the placeholder.  For example, a derived class could allow for
+    periods in the placeholder (e.g. to support a kind of dynamic
+    namespace and attribute path lookup).
 
-    Once the dstring has been created, substitutions can be performed
+    Once the template has been created, substitutions can be performed
     using traditional Python syntax.  For example:
 
+        >>> from string import template
         >>> mapping = dict(name='Guido', country='the Netherlands')
-        >>> s = dstring('${name} was born in ${country})
+        >>> s = template('${name} was born in ${country})
         >>> print s % mapping
         Guido was born in the Netherlands
 
+    Another class is provided which derives from template.  This class
+    is called 'safe_template' and supports rules identical to those
+    above.  The difference between template instances and
+    safe_template instances is that if a placeholder is missing from
+    the interpolation mapping, no KeyError is raised.  Instead, the
+    original placeholder is included in the result string unchanged.
+    For example:
+
+        >>> from string import template, safe_template
+        >>> mapping = dict(name='Guido', country='the Netherlands')
+        >>> s = template('$who was born in $country')
+        >>> print s % mapping
+        Traceback (most recent call last):
+          [...traceback omitted...]
+        KeyError: u'who'
+        >>> s = safe_template('$who was born in $country')
+        >>> print s % mapping
+        $who was born in the Netherlands
+
 
 Why `$' and Braces?
 
@@ -88,15 +108,6 @@ Why `$' and Braces?
     We're copying this from the shell.
 
 
-Reference Implementation
-
-    A reference implementation is available at [4].  The
-    implementation contains the dstring class described above,
-    situated in a new standard library package called 'stringlib'.
-    Inside the reference implementation stringlib package are a few
-    other related nifty tools that aren't described in this PEP.
-
-
 Comparison to PEP 215
 
     PEP 215 describes an alternate proposal for string interpolation.
@@ -124,29 +135,28 @@ Comparison to PEP 215
     quite complex, and make it more difficult to see the substitution
     placeholder in the original $-string.
 
-    The interesting thing is that the dstring class defined in this
+    The interesting thing is that the template class defined in this
     PEP has nothing to say about the values that are substituted for
     the placeholders.  Thus, with a little extra work, it's possible
     to support PEP 215's functionality using existing Python syntax.
 
-    For example, one could define a subclass of dict that allowed a
-    more complex placeholder syntax and a mapping that evaluated those
-    placeholders.
+    For example, one could define subclasses of template and dict that
+    allowed for a more complex placeholder syntax and a mapping that
+    evaluated those placeholders.
 
 
 Internationalization
 
-    The reference implementation accomplishes this magic by parsing
-    the constructor string, transforming $-strings into standard
-    Python %-strings.  dstring caches this value and uses it whenever
-    the special __mod__() method is called via the % operator.
-    However the string value of a dstring is the string that was
-    passed to its constructor.
+    The implementation supports internationalization magic by keeping
+    the original string value intact.  In fact, all the work of the
+    special substitution rules are implemented by overriding the
+    __mod__() operator.  However the string value of a template (or
+    safe_template) is the string that was passed to its constructor.
 
     This approach allows a gettext-based internationalized program to
-    use the dstring instance as a lookup into the catalog; in fact
-    gettext doesn't care that the catalog key is a dstring.  Because
-    the value of the dstring is the original $-string, translators
+    use the template instance as a lookup into the catalog; in fact
+    gettext doesn't care that the catalog key is a template.  Because
+    the value of the template is the original $-string, translators
     also never need to use %-strings.  The right thing will happen at
     run-time.
 
@@ -162,9 +172,6 @@ References
     [3] Guido's python-dev posting from 21-Jul-2002
         http://mail.python.org/pipermail/python-dev/2002-July/026397.html
 
-    [4] Reference implementation
-        http://sourceforge.net/tracker/index.php?func=detail&aid=922115&group_id=5470&atid=305470
-
 
 Copyright