innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Documented the strings_only param to smart_unicode() and force_unicode(). 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6463 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Malcolm Tredinnick 2007-10-07 16:35:32 +00:00
parent 7ab381972e
commit 381453da91
1 changed files with 16 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/unicode.txt
View File

@ -110,19 +110,22 @@ Conversion functions
The ``django.utils.encoding`` module contains a few functions that are handy The ``django.utils.encoding`` module contains a few functions that are handy
for converting back and forth between Unicode and bytestrings. for converting back and forth between Unicode and bytestrings.
* ``smart_unicode(s, encoding='utf-8', errors='strict')`` converts its * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
input to a Unicode string. The ``encoding`` parameter specifies the input converts its input to a Unicode string. The ``encoding`` parameter
encoding. (For example, Django uses this internally when processing form specifies the input encoding. (For example, Django uses this internally
input data, which might not be UTF-8 encoded.) The ``errors`` parameter when processing form input data, which might not be UTF-8 encoded.) The
takes any of the values that are accepted by Python's ``unicode()`` ``strings_only`` parameter, if set to True, will result in Python
function for its error handling. numbers, booleans and ``None`` not being converted to a string (they keep
their original types). The ``errors`` parameter takes any of the values
that are accepted by Python's ``unicode()`` function for its error
handling.
If you pass ``smart_unicode()`` an object that has a ``__unicode__`` If you pass ``smart_unicode()`` an object that has a ``__unicode__``
method, it will use that method to do the conversion. method, it will use that method to do the conversion.
* ``force_unicode(s, encoding='utf-8', errors='strict')`` is identical to * ``force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
``smart_unicode()`` in almost all cases. The difference is when the is identical to ``smart_unicode()`` in almost all cases. The difference
first argument is a `lazy translation`_ instance. While is when the first argument is a `lazy translation`_ instance. While
``smart_unicode()`` preserves lazy translations, ``force_unicode()`` ``smart_unicode()`` preserves lazy translations, ``force_unicode()``
forces those objects to a Unicode string (causing the translation to forces those objects to a Unicode string (causing the translation to
occur). Normally, you'll want to use ``smart_unicode()``. However, occur). Normally, you'll want to use ``smart_unicode()``. However,
@ -132,11 +135,10 @@ for converting back and forth between Unicode and bytestrings.
* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')`` * ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
is essentially the opposite of ``smart_unicode()``. It forces the first is essentially the opposite of ``smart_unicode()``. It forces the first
argument to a bytestring. The ``strings_only`` parameter, if set to True, argument to a bytestring. The ``strings_only`` parameter has the same
will result in Python integers, booleans and ``None`` not being behaviour as for ``smart_unicode()`` and ``force_unicode()``. This is
converted to a string (they keep their original types). This is slightly slightly different semantics from Python's builtin ``str()`` function,
different semantics from Python's builtin ``str()`` function, but the but the difference is needed in a few places within Django's internals.
difference is needed in a few places within Django's internals.
Normally, you'll only need to use ``smart_unicode()``. Call it as early as Normally, you'll only need to use ``smart_unicode()``. Call it as early as
possible on any input data that might be either Unicode or a bytestring, and possible on any input data that might be either Unicode or a bytestring, and