schema-evolution: updated from trunk/HEAD (r5787)

git-svn-id: http://code.djangoproject.com/svn/django/branches/schema-evolution@5788 bcc190cf-cafb-0310-a4f2-bffc1f526a37

5 files changed, 126 insertions, 16 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index efe4d47513..a05624db68 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -99,7 +99,7 @@ custom methods:
       should prefer using ``is_authenticated()`` to this method.
 
     * ``is_authenticated()`` -- Always returns ``True``. This is a way to
-      tell if the user has been authenticated. This does not imply any 
+      tell if the user has been authenticated. This does not imply any
       permissions, and doesn't check if the user is active - it only indicates
       that the user has provided a valid username and password.
 
@@ -114,6 +114,18 @@ custom methods:
       string is the correct password for the user. (This takes care of the
       password hashing in making the comparison.)
 
+    * ``set_unusable_password()`` -- **New in Django development version.**
+      Marks the user as having no password set.  This isn't the same as having
+      a blank string for a password. ``check_password()`` for this user will
+      never return ``True``. Doesn't save the ``User`` object.
+
+      You may need this if authentication for your application takes place
+      against an existing external source such as an LDAP directory.
+
+    * ``has_usable_password()`` -- **New in Django development version.**
+      Returns ``False`` if ``set_unusable_password()`` has been called for this
+      user.
+
     * ``get_group_permissions()`` -- Returns a list of permission strings that
       the user has, through his/her groups.
 
@@ -126,7 +138,7 @@ custom methods:
 
     * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the
       specified permissions, where each perm is in the format
-      ``"package.codename"``. If the user is inactive, this method will 
+      ``"package.codename"``. If the user is inactive, this method will
       always return ``False``.
 
     * ``has_module_perms(package_name)`` -- Returns ``True`` if the user has
@@ -152,9 +164,11 @@ Manager functions
 
 The ``User`` model has a custom manager that has the following helper functions:
 
-    * ``create_user(username, email, password)`` -- Creates, saves and returns
-      a ``User``. The ``username``, ``email`` and ``password`` are set as
-      given, and the ``User`` gets ``is_active=True``.
+    * ``create_user(username, email, password=None)`` -- Creates, saves and
+      returns a ``User``. The ``username``, ``email`` and ``password`` are set
+      as given, and the ``User`` gets ``is_active=True``.
+
+      If no password is provided, ``set_unusable_password()`` will be called.
 
       See _`Creating users` for example usage.
 
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 0e8dff68f4..9dbb865a58 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -279,6 +279,22 @@ Please follow these coding standards when writing code for inclusion in Django:
     * Mark all strings for internationalization; see the `i18n documentation`_
       for details.
 
+    * In docstrings, use "action words," like so::
+
+          def foo():
+              """
+              Calculates something and returns the result.
+              """
+              pass
+
+      Here's an example of what not to do::
+
+          def foo():
+              """
+              Calculate something and return the result.
+              """
+              pass
+
     * Please don't put your name in the code you contribute. Our policy is to
       keep contributors' names in the ``AUTHORS`` file distributed with Django
       -- not scattered throughout the codebase itself. Feel free to include a
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 8e664ce3c1..975a166b6b 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -20,7 +20,7 @@ a weblog application::
 
     class Author(models.Model):
         name = models.CharField(maxlength=50)
-        email = models.URLField()
+        email = models.EmailField()
 
         def __unicode__(self):
             return self.name
@@ -1891,8 +1891,8 @@ get_object_or_404()
 One common idiom to use ``get()`` and raise ``Http404`` if the
 object doesn't exist. This idiom is captured by ``get_object_or_404()``.
 This function takes a Django model as its first argument and an
-arbitrary number of keyword arguments, which it passes to the manager's
-``get()`` function. It raises ``Http404`` if the object doesn't
+arbitrary number of keyword arguments, which it passes to the default
+manager's ``get()`` function. It raises ``Http404`` if the object doesn't
 exist. For example::
 
     # Get the Entry with a primary key of 3
@@ -1901,7 +1901,7 @@ exist. For example::
 When you provide a model to this shortcut function, the default manager
 is used to execute the underlying ``get()`` query. If you don't want to
 use the default manager, or if you want to search a list of related objects,
-you can provide ``get_object_or_404()`` with a manager object instead.
+you can provide ``get_object_or_404()`` with a ``Manager`` object instead.
 For example::
 
     # Get the author of blog instance e with a name of 'Fred'
@@ -1911,6 +1911,14 @@ For example::
     # entry with a primary key of 3
     e = get_object_or_404(Entry.recent_entries, pk=3)
 
+**New in Django development version:** The first argument to
+``get_object_or_404()`` can be a ``QuerySet`` object. This is useful in cases
+where you've defined a custom manager method. For example::
+
+    # Use a QuerySet returned from a 'published' method of a custom manager
+    # in the search for an entry with primary key of 5
+    e = get_object_or_404(Entry.objects.published(), pk=5)
+
 get_list_or_404()
 -----------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index f14aa7352c..6a706c57cb 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1052,6 +1052,44 @@ create your tables. It's not called at any other time, so it can afford to
 execute slightly complex code, such as the ``DATABASE_ENGINE`` check in the
 above example.
 
+Some database column types accept parameters, such as ``CHAR(25)``, where the
+parameter ``25`` represents the maximum column length. In cases like these,
+it's more flexible if the parameter is specified in the model rather than being
+hard-coded in the ``db_type()`` method. For example, it wouldn't make much
+sense to have a ``CharMaxlength25Field``, shown here::
+
+    # This is a silly example of hard-coded parameters.
+    class CharMaxlength25Field(models.Field):
+        def db_type(self):
+            return 'char(25)'
+
+    # In the model:
+    class MyModel(models.Model):
+        # ...
+        my_field = CharMaxlength25Field()
+
+The better way of doing this would be to make the parameter specifiable at run
+time -- i.e., when the class is instantiated. To do that, just implement
+``__init__()``, like so::
+
+    # This is a much more flexible example.
+    class BetterCharField(models.Field):
+        def __init__(self, maxlength, *args, **kwargs):
+            self.maxlength = maxlength
+            super(BetterCharField, self).__init__(*args, **kwargs)
+
+        def db_type(self):
+            return 'char(%s)' % self.maxlength
+
+    # In the model:
+    class MyModel(models.Model):
+        # ...
+        my_field = BetterCharField(25)
+
+Note that if you implement ``__init__()`` on a ``Field`` subclass, it's
+important to call ``Field.__init__()`` -- i.e., the parent class'
+``__init__()`` method.
+
 Meta options
 ============
 
diff --git a/docs/testing.txt b/docs/testing.txt
index 4158e9277a..f4b78273ce 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -450,6 +450,9 @@ look like::
         def setUp(self):
             # test definitions as before
 
+        def testFluffyAnimals(self):
+            # A test that uses the fixtures
+
 At the start of each test case, before ``setUp()`` is run, Django will
 flush the database, returning the database the state it was in directly
 after ``syncdb`` was called. Then, all the named fixtures are installed.
@@ -483,8 +486,8 @@ that can be useful in testing the behavior of web sites.
 
 ``assertContains(response, text, count=None, status_code=200)``
     Assert that a response indicates that a page could be retrieved and
-    produced the nominated status code, and that ``text`` in the content 
-    of the response. If ``count`` is provided, ``text`` must occur exactly 
+    produced the nominated status code, and that ``text`` in the content
+    of the response. If ``count`` is provided, ``text`` must occur exactly
     ``count`` times in the response.
 
 ``assertFormError(response, form, field, errors)``
@@ -571,6 +574,18 @@ but you only want to run the animals unit tests, run::
 
     $ ./manage.py test animals
 
+**New in Django development version:** If you use unit tests, you can be more
+specific in the tests that are executed. To run a single test case in an
+application (for example, the AnimalTestCase described previously), add the
+name of the test case to the label on the command line::
+
+    $ ./manage.py test animals.AnimalTestCase
+
+**New in Django development version:** To run a single test method inside a
+test case, add the name of the test method to the label::
+
+    $ ./manage.py test animals.AnimalTestCase.testFluffyAnimals
+
 When you run your tests, you'll see a bunch of text flow by as the test
 database is created and models are initialized. This test database is
 created from scratch every time you run your tests.
@@ -662,17 +677,36 @@ framework that can be executed from Python code.
 Defining a test runner
 ----------------------
 By convention, a test runner should be called ``run_tests``; however, you
-can call it anything you want. The only requirement is that it accept two
-arguments:
+can call it anything you want. The only requirement is that it has the
+same arguments as the Django test runner:
 
-``run_tests(module_list, verbosity=1)``
-    The module list is the list of Python modules that contain the models to be
-    tested. This is the same format returned by ``django.db.models.get_apps()``
+``run_tests(test_labels, verbosity=1, interactive=True, extra_tests=[])``
+    
+    **New in Django development version:** ``test_labels`` is a list of
+    strings describing the tests to be run. A test label can take one of
+    three forms:
+
+        * ``app.TestCase.test_method`` - Run a single test method in a test case
+        * ``app.TestCase`` - Run all the test methods in a test case
+        * ``app`` - Search for and run all tests in the named application.
+
+    If ``test_labels`` has a value of ``None``, the test runner should run
+    search for tests in all the applications in ``INSTALLED_APPS``.
 
     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.
 
+    **New in Django development version:** If ``interactive`` is ``True``, the
+    test suite may ask the user for instructions when the test suite is
+    executed. An example of this behavior would be asking for permission to
+    delete an existing test database. If ``interactive`` is ``False``, the
+    test suite must be able to run without any manual intervention.
+
+    ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
+    suite that is executed by the test runner. These extra tests are run
+    in addition to those discovered in the modules listed in ``module_list``.
+
     This method should return the number of tests that failed.
 
 Testing utilities