Permalink
Browse files

unicode: Made some documentation edits and inconsequential typo fixes…

… throughout code

git-svn-id: http://code.djangoproject.com/svn/django/branches/unicode@5597 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent c62d6ee commit 1feda14c8e14eb4d716d725a58add6dbbb04bd5f @adrianholovaty adrianholovaty committed Jul 3, 2007
@@ -14,7 +14,7 @@ def get_for_model(self, model):
try:
ct = CONTENT_TYPE_CACHE[key]
except KeyError:
- # The unicode() is needed around opts.verbose_name because it might
+ # The smart_unicode() is needed around opts.verbose_name_raw because it might
# be a django.utils.functional.__proxy__ object.
ct, created = self.model._default_manager.get_or_create(app_label=key[0],
model=key[1], defaults={'name': smart_unicode(opts.verbose_name_raw)})
@@ -7,7 +7,7 @@
def add_domain(domain, url):
if not url.startswith('http://'):
- # 'url' must already be ASCII and URL-quoted, so no need for encodign
+ # 'url' must already be ASCII and URL-quoted, so no need for encoding
# conversions here.
url = u'http://%s%s' % (domain, url)
return url
View
@@ -50,7 +50,7 @@ def is_secure(self):
def _set_encoding(self, val):
"""
Sets the encoding used for GET/POST accesses. If the GET or POST
- dictionary has already been created it is removed and recreated on the
+ dictionary has already been created, it is removed and recreated on the
next access (so that it is decoded correctly).
"""
self._encoding = val
@@ -101,7 +101,7 @@ class QueryDict(MultiValueDict):
This is immutable unless you create a copy of it.
Values retrieved from this class are converted from the default encoding to
- unicode (this is done on retrieval, rather than input to avoid breaking
+ unicode (this is done on retrieval, rather than input, to avoid breaking
references or mutating referenced objects).
"""
def __init__(self, query_string, mutable=False, encoding=None):
@@ -116,7 +116,8 @@ def make_list(value):
def slugify(value):
"Converts to lowercase, removes non-alpha chars and converts spaces to hyphens"
- # Don't compile patterns as unicode because \w then would mean any letter. Slugify is effectively an asciiization.
+ # Don't compile patterns as unicode because \w then would mean any letter.
+ # Slugify is effectively a conversion to ASCII.
value = re.sub('[^\w\s-]', '', value).strip().lower()
return re.sub('[-\s]+', '-', value)
slugify = stringfilter(slugify)
View
@@ -68,26 +68,24 @@ In Python code
Standard translation
~~~~~~~~~~~~~~~~~~~~
-Specify a translation string by using the function ``ugettext()``. Since you
-may well be typing this a lot, it's often worthwhile importing it as a shorter
-alias and ``_`` is a very common choice.
+Specify a translation string by using the function ``ugettext()``. It's
+convention to import this as a shorter alias, ``_``, to save typing.
.. note::
Python's standard library ``gettext`` module installs ``_()`` into the
global namespace, as an alias for ``gettext()``. In Django, we have chosen
not to follow this practice, for a couple of reasons:
- 1. For international character set (unicode) support, you really wanting
- to be using ``ugettext()``, rather than ``gettext()``. Sometimes, you
- should be using ``ugettext_lazy()`` as the default translation method
- for a particular file. By not installing ``_`` directly, the
- developer has to think about which is the most appropriate function
- to use.
+ 1. For international character set (Unicode) support, ``ugettext()`` is
+ more useful than ``gettext()``. Sometimes, you should be using
+ ``ugettext_lazy()`` as the default translation method for a particular
+ file. Without ``_()`` in the global namespace, the developer has to
+ think about which is the most appropriate translation function.
- 2. Python's interactive shell uses ``_`` to represent "the previous
- result". This is also used in doctest tests and having ``_()`` causes
- interference. Explicitly importing ``ugettext()`` as ``_()`` avoids
- this problem.
+ 2. The underscore character (``_``) is used to represent "the previous
+ result" in Python's interactive shell and doctest tests. Installing a
+ global ``_()`` function causes interference. Explicitly importing
+ ``ugettext()`` as ``_()`` avoids this problem.
In this example, the text ``"Welcome to my site."`` is marked as a translation
string::
@@ -98,7 +96,7 @@ string::
output = _("Welcome to my site.")
return HttpResponse(output)
-Obviously you could code this without using the alias. This example is
+Obviously, you could code this without using the alias. This example is
identical to the previous one::
from django.utils.translation import ugettext
@@ -300,7 +298,7 @@ Working with lazy translation objects
=====================================
Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
-and utility functions is a common operation. When you are working with these
+and utility functions is a common operation. When you're working with these
objects elsewhere in your code, you should ensure that you don't accidentally
convert them to strings, because they should be converted as late as possible
(so that the correct locale is in effect). This necessitates the use of a
@@ -328,20 +326,20 @@ rendering time).
The allow_lazy() decorator
--------------------------
-There are a lot of useful utility functions in Django (particularly in
-``django.utils``) that take a string as their first argument and do something
-to that string. These functions are used by template filters as well as
-directly in other code.
-
-If you write your own similar functions, you will rapidly come across the
-problem of what to do when the first argument is a lazy translation object.
-You don't want to convert it to a string immediately, because you may be using
-this function outside of a view (and hence the current thread's locale setting
-will not be correct). For cases like this, the
-``django.utils.functional.allow_lazy()`` decorator will be useful. It modifies
-the function so that *if* it is called with a lazy translation as the first
-argument, the function evaluation is delayed until it needs to be converted to
-a string.
+Django offers many utility functions (particularly in ``django.utils``) that
+take a string as their first argument and do something to that string. These
+functions are used by template filters as well as directly in other code.
+
+If you write your own similar functions and deal with translations, you'll
+face the problem of what to do when the first argument is a lazy translation
+object. You don't want to convert it to a string immediately, because you might
+be using this function outside of a view (and hence the current thread's locale
+setting will not be correct).
+
+For cases like this, use the ``django.utils.functional.allow_lazy()``
+decorator. It modifies the function so that *if* it's called with a lazy
+translation as the first argument, the function evaluation is delayed until it
+needs to be converted to a string.
For example::
@@ -353,9 +351,9 @@ For example::
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
-a number of extra arguments specifying the type(s) that the original function
-can return. Usually, it will be enough to just include ``unicode`` here and
-ensure that your function returns Unicode strings.
+a number of extra arguments (``*args``) specifying the type(s) that the
+original function can return. Usually, it's enough to include ``unicode`` here
+and ensure that your function returns only Unicode strings.
Using this decorator means you can write your function and assume that the
input is a proper string, then add support for lazy translation objects at the
View
@@ -1044,11 +1044,11 @@ iriencode
~~~~~~~~~
Converts an IRI (Internationalized Resource Identifier) to a string that is
-suitable for including in a URL. This is necessary if you are trying to use
+suitable for including in a URL. This is necessary if you're trying to use
strings containing non-ASCII characters in a URL.
-You can use this filter after you have used the ``urlencode`` filter on a
-string, without harm.
+It's safe to use this filter on a string that has already gone through the
+``urlencode`` filter.
join
~~~~
View
@@ -492,20 +492,21 @@ your own sanity when dealing with the interactive prompt, but also because
objects' representations are used throughout Django's automatically-generated
admin.
-.. admonition:: Why ``__unicode__`` and not ``__str__``?
-
- If you are wondering why we add a ``__unicode__()`` method, rather than a
- simple ``__str__()`` method, it is because Django models will contain
- unicode strings by default. The values returned from the database, for
- example, are all unicode strings. In most cases, your code should be
- prepared to handle non-ASCII characters and this is a litle fiddly in
- ``__str__()`` methods, since you have to worry about which encoding to
- use, amongst other things. If you create a ``__unicode__()`` method,
- Django will provide a ``__str__()`` method that calls your
- ``__unicode__()`` and then converts the result to UTF-8 strings when
- required. So ``unicode(p)`` will return a unicode string and ``str(p)``
- will return a normal string, with the characters encoded as UTF-8 when
- necessary..
+.. admonition:: Why ``__unicode__()`` and not ``__str__()``?
+
+ If you're familiar with Python, you might be in the habit of adding
+ ``__str__()`` methods to your classes, not ``__unicode__()`` methods.
+ We use ``__unicode__()`` here because Django models deal with Unicode by
+ default. All data stored in your database is converted to Unicode when it's
+ returned.
+
+ Django models have a default ``__str__()`` method that calls ``__unicode__()``
+ and converts the result to a UTF-8 bytestring. This means that ``unicode(p)``
+ will return a Unicode string, and ``str(p)`` will return a normal string,
+ with characters encoded as UTF-8.
+
+ If all of this is jibberish to you, just remember to add ``__unicode__()``
+ methods to your models. With any luck, things should Just Work for you.
Note these are normal Python methods. Let's add a custom method, just for
demonstration::
Oops, something went wrong.

0 comments on commit 1feda14

Please sign in to comment.