sqlalchemy: Merged revisions 3770 to 3831 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/sqlalchemy@3832 bcc190cf-cafb-0310-a4f2-bffc1f526a37

9 files changed, 136 insertions, 28 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index f161e9d357..31a894512a 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -456,6 +456,10 @@ As a shortcut, you can use the convenient ``user_passes_test`` decorator::
         # ...
     my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)
 
+We are using this particular test as a relatively simple example, however be
+aware that if you just want to test if a permission is available to a user,
+you can use the ``permission_required()`` decorator described below.
+
 Here's the same thing, using Python 2.4's decorator syntax::
 
     from django.contrib.auth.decorators import user_passes_test
@@ -488,6 +492,24 @@ Example in Python 2.4 syntax::
     def my_view(request):
         # ...
 
+The permission_required decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since checking whether a user has a particular permission available to them is a
+relatively common operation, Django provides a shortcut for that particular
+case: the ``permission_required()`` decorator. Using this decorator, the
+earlier example can be written as::
+
+    from django.contrib.auth.decorators import permission_required
+     
+    def my_view(request):
+        # ...
+     
+    my_view = permission_required('polls.can_vote')(my_view)
+
+Note that ``permission_required()`` also takes an optional ``login_url``
+parameter.
+
 Limiting access to generic views
 --------------------------------
 
@@ -677,7 +699,7 @@ timestamps.
 Messages are used by the Django admin after successful actions. For example,
 ``"The poll Foo was created successfully."`` is a message.
 
-The API is simple::
+The API is simple:
 
     * To create a new message, use
       ``user_obj.message_set.create(message='message_text')``.
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 3d101c3241..7ecda7425c 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -247,18 +247,23 @@ Django tarball. It's our policy to make sure all tests pass at all times.
 
 The tests cover:
 
-    * Models and the database API (``tests/testapp/models``).
-    * The cache system (``tests/otherthests/cache.py``).
-    * The ``django.utils.dateformat`` module (``tests/othertests/dateformat.py``).
-    * Database typecasts (``tests/othertests/db_typecasts.py``).
-    * The template system (``tests/othertests/templates.py`` and
-      ``tests/othertests/defaultfilters.py``).
-    * ``QueryDict`` objects (``tests/othertests/httpwrappers.py``).
-    * Markup template tags (``tests/othertests/markup.py``).
-    * The ``django.utils.timesince`` module (``tests/othertests/timesince.py``).
+    * Models and the database API (``tests/modeltests/``).
+    * The cache system (``tests/regressiontests/cache.py``).
+    * The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``).
+    * Database typecasts (``tests/regressiontests/db_typecasts/``).
+    * The template system (``tests/regressiontests/templates/`` and
+      ``tests/regressiontests/defaultfilters/``).
+    * ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``).
+    * Markup template tags (``tests/regressiontests/markup/``).
 
 We appreciate any and all contributions to the test suite!
 
+The Django tests all use the testing infrastructure that ships with Django for
+testing applications. See `Testing Django Applications`_ for an explanation of
+how to write new tests.
+
+.. _Testing Django Applications: http://www.djangoproject.com/documentation/testing/
+
 Running the unit tests
 ----------------------
 
@@ -268,10 +273,14 @@ To run the tests, ``cd`` to the ``tests/`` directory and type::
 
 Yes, the unit tests need a settings module, but only for database connection
 info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``.
-
-The unit tests will not touch your database; they create a new database, called
-``django_test_db``, which is deleted when the tests are finished. This means
-your user account needs permission to execute ``CREATE DATABASE``.
+You will also need a ``ROOT_URLCONF`` setting (it's value is ignored; it just
+needs to be present) and a ``SITE_ID`` setting (any integer value will do) in
+order for all the tests to pass.
+
+The unit tests will not touch your existing databases; they create a new
+database, called ``django_test_db``, which is deleted when the tests are
+finished. This means your user account needs permission to execute ``CREATE
+DATABASE``.
 
 Requesting features
 ===================
diff --git a/docs/db-api.txt b/docs/db-api.txt
index bd178dbd7d..0d1f049601 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1140,7 +1140,7 @@ The pk lookup shortcut
 ----------------------
 
 For convenience, Django provides a ``pk`` lookup type, which stands for
-"primary_key". This is shorthand for "an exact lookup on the primary-key."
+"primary_key". 
 
 In the example ``Blog`` model, the primary key is the ``id`` field, so these
 three statements are equivalent::
@@ -1149,6 +1149,14 @@ three statements are equivalent::
     Blog.objects.get(id=14) # __exact is implied
     Blog.objects.get(pk=14) # pk implies id__exact
 
+The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 
+can be combined with ``pk`` to perform a query on the primary key of a model::
+
+    # Get blogs entries  with id 1, 4 and 7
+    Blog.objects.filter(pk__in=[1,4,7])
+    # Get all blog entries with id > 14
+    Blog.objects.filter(pk__gt=14) 
+    
 ``pk`` lookups also work across joins. For example, these three statements are
 equivalent::
 
@@ -1511,7 +1519,7 @@ Many-to-many relationships
 --------------------------
 
 Both ends of a many-to-many relationship get automatic API access to the other
-end. The API works just as a "backward" one-to-many relationship. See _Backward
+end. The API works just as a "backward" one-to-many relationship. See Backward_
 above.
 
 The only difference is in the attribute naming: The model that defines the
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index ffafc83972..ed162f0520 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -352,8 +352,9 @@ options.
 
 **New in Django development version**
 
-Inform django-admin that the user should NOT be prompted for any input. Useful if
-the django-admin script will be executed as an unattended, automated script.
+Inform django-admin that the user should NOT be prompted for any input. Useful
+if the django-admin script will be executed as an unattended, automated
+script.
 
 --noreload
 ----------
@@ -383,6 +384,19 @@ Verbosity determines the amount of notification and debug information that
 will be printed to the console. '0' is no output, '1' is normal output,
 and `2` is verbose output.
 
+--adminmedia
+------------
+
+**New in Django development version**
+
+Example usage::
+    django-admin.py manage.py --adminmedia=/tmp/new-admin-style/
+
+Tell Django where to find the various stylesheets and Javascript files for the
+admin interface when running the development server. Normally these files are
+served out of the Django source tree, but since some designers change these
+files for their site, this option allows you to test against custom versions.
+
 Extra niceties
 ==============
 
diff --git a/docs/forms.txt b/docs/forms.txt
index d6ef6f791b..0ffb0bdcb7 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -136,7 +136,7 @@ template::
     {% endblock %}
 
 Before we get back to the problems with these naive set of views, let's go over
-some salient points of the above template::
+some salient points of the above template:
 
     * Field "widgets" are handled for you: ``{{ form.field }}`` automatically
       creates the "right" type of widget for the form, as you can see with the
@@ -148,8 +148,8 @@ some salient points of the above template::
       If you must use tables, use tables. If you're a semantic purist, you can
       probably find better HTML than in the above template.
 
-    * To avoid name conflicts, the ``id``s of form elements take the form
-      "id_*fieldname*".
+    * To avoid name conflicts, the ``id`` values of form elements take the
+      form "id_*fieldname*".
 
 By creating a creation form we've solved problem number 3 above, but we still
 don't have any validation. Let's revise the validation issue by writing a new
@@ -481,6 +481,33 @@ the data being validated.
 Also, because consistency in user interfaces is important, we strongly urge you
 to put punctuation at the end of your validation messages.
 
+When Are Validators Called?
+---------------------------
+
+After a form has been submitted, Django first checks to see that all the
+required fields are present and non-empty. For each field that passes that
+test *and if the form submission contained data* for that field, all the
+validators for that field are called in turn. The emphasised portion in the
+last sentence is important: if a form field is not submitted (because it
+contains no data -- which is normal HTML behaviour), the validators are not
+run against the field.
+
+This feature is particularly important for models using
+``models.BooleanField`` or custom manipulators using things like
+``forms.CheckBoxField``. If the checkbox is not selected, it will not
+contribute to the form submission.
+
+If you would like your validator to *always* run, regardless of whether the
+field it is attached to contains any data, set the ``always_test`` attribute
+on the validator function. For example::
+
+    def my_custom_validator(field_data, all_data):
+        # ...
+
+    my_custom_validator.always_test = True
+
+This validator will always be executed for any field it is attached to.
+
 Ready-made Validators
 ---------------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index b46a11c463..c6c4200239 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -543,7 +543,9 @@ The default value for the field.
 ``editable``
 ~~~~~~~~~~~~
 
-If ``False``, the field will not be editable in the admin. Default is  ``True``.
+If ``False``, the field will not be editable in the admin or via form
+processing using the object's ``AddManipulator`` or ``ChangeManipulator``
+classes. Default is  ``True``.
 
 ``help_text``
 ~~~~~~~~~~~~~
diff --git a/docs/serialization.txt b/docs/serialization.txt
index 25199e7a50..694e2d25db 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -96,6 +96,21 @@ Django "ships" with a few included serializers:
 .. _json: http://json.org/
 .. _simplejson: http://undefined.org/python/#simplejson
 
+Notes For Specific Serialization Formats
+----------------------------------------
+
+json
+~~~~
+
+If you are using UTF-8 (or any other non-ASCII encoding) data with the JSON
+serializer, you must pass ``ensure_ascii=False`` as a parameter to the
+``serialize()`` call. Otherwise the output will not be encoded correctly.
+
+For example::
+
+    json_serializer = serializers.get_serializer("json")
+    json_serializer.serialize(queryset, ensure_ascii=False, stream=response)
+
 Writing custom serializers
 ``````````````````````````
 
diff --git a/docs/settings.txt b/docs/settings.txt
index b927b62ca7..65113b3c30 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -596,6 +596,12 @@ Whether to prepend the "www." subdomain to URLs that don't have it. This is
 only used if ``CommonMiddleware`` is installed (see the `middleware docs`_).
 See also ``APPEND_SLASH``.
 
+PROFANITIES_LIST
+----------------
+
+A list of profanities that will trigger a validation error when the
+``hasNoProfanities`` validator is called.
+
 ROOT_URLCONF
 ------------
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 950b122339..bc05d769ad 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -763,17 +763,17 @@ will use the function's name as the tag name.
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many template tags take a single argument -- a string or a template variable
-reference -- and return a string after doing some processing based solely on
+Many template tags take a number of arguments -- strings or a template variables
+-- and return a string after doing some processing based solely on
 the input argument and some external information. For example, the
 ``current_time`` tag we wrote above is of this variety: we give it a format
 string, it returns the time as a string.
 
 To ease the creation of the types of tags, Django provides a helper function,
 ``simple_tag``. This function, which is a method of
-``django.template.Library``, takes a function that accepts one argument, wraps
-it in a ``render`` function and the other necessary bits mentioned above and
-registers it with the template system.
+``django.template.Library``, takes a function that accepts any number of
+arguments, wraps it in a ``render`` function and the other necessary bits
+mentioned above and registers it with the template system.
 
 Our earlier ``current_time`` function could thus be written like this::
 
@@ -789,11 +789,16 @@ In Python 2.4, the decorator syntax also works::
         ...
 
 A couple of things to note about the ``simple_tag`` helper function:
-    * Only the (single) argument is passed into our function.
     * Checking for the required number of arguments, etc, has already been
       done by the time our function is called, so we don't need to do that.
     * The quotes around the argument (if any) have already been stripped away,
       so we just receive a plain string.
+    * If the argument was a template variable, our function is passed the
+      current value of the variable, not the variable itself.
+
+When your template tag does not need access to the current context, writing a
+function to work with the input values and using the ``simple_tag`` helper is
+the easiest way to create a new tag.
 
 Inclusion tags
 ~~~~~~~~~~~~~~