diff options
| -rw-r--r-- | Doc/tut/tut.tex | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index 73222ff..102ffea 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -4836,6 +4836,83 @@ with group separators: \end{verbatim} +\section{Templating\label{templating}} + +The \ulink{\module{string}}{../lib/module-string.html} module includes a +versatile \class{Template} class with a simplified syntax suitable for +editing by end-users. This allows users to customize their applications +without having to alter the Python program. + +The format uses \samp{\$} for placeholder names that are valid Python +identifiers (alphanumeric characters and underscores). Surrounding the +placeholder with braces allows it to be followed by more alphanumeric letters +with no intervening spaces. \samp{\$\$} is the way to create a single escaped +\samp{\$}: + +\begin{verbatim} +>>> from string import Template +>>> t = Template('${village}folk send $$10 to $cause.') +>>> t.substitute(village='nottingham', cause='the ditch fund') +'nottinghamfolk send $10 to the ditch fund.' +\end{verbatim} + +The \method{substitute} method raises a \exception{KeyError} when a +placeholder is not supplied in a dictionary or a keyword argument. +For mail-merge style applications, user supplied data may be incomplete +and the \method{safe_substitute} method may be more appropriate --- it +will leave placeholders unchanged if data is missing: + +\begin{verbatim} +>>> t = Template('Return the $item to $owner.') +>>> d = dict(item='unladen swallow') +>>> t.substitute(d) +Traceback (most recent call last): + . . . +KeyError: 'owner' +>>> t.safe_substitute(d) +'Return the unladen swallow to $owner.' +\end{verbatim} + +Template subclasses can specify a custom delimiter. For example, a batch +renaming utility for a photo browser may elect to use percent signs for +metadata such as the current date, image sequence number, or file format: + +\begin{verbatim} +>>> import time, os.path +>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg'] +>>> class BatchRename(Template): +... delimiter = '%' +>>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format): ') +Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f + +>>> rename = BatchRename(fmt) +>>> date = time.strftime('%d%b%y') +>>> for i, filename in enumerate(photofiles): +... base, ext = os.path.splitext(filename) +... newname = rename.substitute(d=date, n=i, f=ext) +... print '%s --> %s' % (filename, newname) + +img_1074.jpg --> Ashley_0.jpg +img_1076.jpg --> Ashley_1.jpg +img_1077.jpg --> Ashley_2.jpg +\end{verbatim} + +For internationalization applications, it may be appropriate to coerce all +templates to \class{unicode}. This can be done with subclassing and +overriding the \method{__init__} method: + +\begin{verbatim} +>>> class UnicodeTemplate(unicode, Template): +... def __init__(self, template): +... self.template = unicode(template) +>>> t = UnicodeTemplate('Knights who say $what') +>>> t.substitute(what='Ni') +u'Knights who say Ni' +>>> t.capitalize() +u'Knights who say $what' +\end{verbatim} + + \section{Working with Binary Data Record Layouts\label{binary-formats}} The \ulink{\module{struct}}{../lib/module-struct.html} module provides |