From d202377f2a356c5e2485af61372a87a904cbb844 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Mon, 2 Apr 2012 13:34:32 -0700 Subject: [PATCH] Added to README a section on unicode string handling. --- README.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.rst b/README.rst index 39f38401..ae3ef8f0 100644 --- a/README.rst +++ b/README.rst @@ -73,6 +73,33 @@ Pull it together:: u'Hello, Pizza!' +Unicode +======= + +This section describes Pystache's handling of unicode, strings, and encodings. +Pystache's template rendering methods output only unicode. Moreover, +internally Pystache uses only unicode strings. For input, Pystache accepts +both ``unicode`` and ``str`` strings. + +The Renderer class supports a number of attributes that control how it +converts ``str`` strings to unicode on input. These attributes include +the file_encoding, string_encoding, and decode_errors attributes. + +The file_encoding attribute is the encoding the renderer uses to convert +to unicode any files read from the file system. Similarly, string_encoding +is the encoding the renderer uses to convert any other strings of type str +to unicode (e.g. context values of type ``str``). The decode_errors +attribute is what the renderer passes as the ``errors`` argument to +Python's built-in `unicode()`_ function. The valid values are 'strict', +'ignore', or 'replace'. + +Each of these attributes can be set via the Renderer class's constructor +using a keyword argument of the same name. In addition, the file_encoding +attribute can be controlled on a per-view basis by subclassing the +`TemplateSpec` class. The attributes default to values set in Pystache's +``defaults`` module. + + Test It ======= @@ -136,4 +163,5 @@ Author .. _PyPI: http://pypi.python.org/pypi/pystache .. _Pystache: https://github.com/defunkt/pystache .. _semantically versioned: http://semver.org +.. _unicode(): http://docs.python.org/library/functions.html#unicode .. _version 1.0.3: https://github.com/mustache/spec/tree/48c933b0bb780875acbfd15816297e263c53d6f7