mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 10:59:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Refs #27753 -- Favored force/smart_str() over force/smart_text().

Browse source
This commit is contained in:
Aymeric Augustin 2017-01-26 10:08:08 +01:00 • committed by Tim Graham
parent 24b82cd201
commit 3bb6a4390c
21 changed files with 84 additions and 101 deletions
Download patch file Download diff file Expand all files Collapse all files

27
docs/ref/unicode.txt
View file

@ -108,7 +108,7 @@ Conversion functions
The ``django.utils.encoding`` module contains a few functions that are handy
for converting back and forth between strings and bytestrings.
* ``smart_text(s, encoding='utf-8', strings_only=False, errors='strict')``
* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
converts its input to a string. The ``encoding`` parameter
specifies the input encoding. (For example, Django uses this internally
when processing form input data, which might not be UTF-8 encoded.) The
@ -118,24 +118,23 @@ for converting back and forth between strings and bytestrings.
that are accepted by Python's ``str()`` function for its error
handling.
* ``force_text(s, encoding='utf-8', strings_only=False,
errors='strict')`` is identical to ``smart_text()`` in almost all
cases. The difference is when the first argument is a :ref:`lazy
translation <lazy-translations>` instance. While ``smart_text()``
preserves lazy translations, ``force_text()`` forces those objects to a
string (causing the translation to occur). Normally, you'll want
to use ``smart_text()``. However, ``force_text()`` is useful in
template tags and filters that absolutely *must* have a string to work
with, not just something that can be converted to a string.
* ``force_str(s, encoding='utf-8', strings_only=False, errors='strict')`` is
identical to ``smart_str()`` in almost all cases. The difference is when the
first argument is a :ref:`lazy translation <lazy-translations>` instance.
While ``smart_str()`` preserves lazy translations, ``force_str()`` forces
those objects to a string (causing the translation to occur). Normally,
you'll want to use ``smart_str()``. However, ``force_str()`` is useful in
template tags and filters that absolutely *must* have a string to work with,
not just something that can be converted to a string.
* ``smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')``
is essentially the opposite of ``smart_text()``. It forces the first
is essentially the opposite of ``smart_str()``. It forces the first
argument to a bytestring. The ``strings_only`` parameter has the same
behavior as for ``smart_text()`` and ``force_text()``. This is
behavior as for ``smart_str()`` and ``force_str()``. This is
slightly different semantics from Python's builtin ``str()`` function,
but the difference is needed in a few places within Django's internals.
Normally, you'll only need to use ``force_text()``. Call it as early as
Normally, you'll only need to use ``force_str()``. Call it as early as
possible on any input data that might be either a string or a bytestring, and
from then on, you can treat the result as always being a string.
@ -280,7 +279,7 @@ A couple of tips to remember when writing your own template tags and filters:
* Always return strings from a template tag's ``render()`` method
and from template filters.
* Use ``force_text()`` in preference to ``smart_text()`` in these
* Use ``force_str()`` in preference to ``smart_str()`` in these
places. Tag rendering and filter calls occur as the template is being
rendered, so there is no advantage to postponing the conversion of lazy
translation objects into strings. It's easier to work solely with