multi-auth: Merged to [3151]archive/attic/multi-authattic/multi-auth

git-svn-id: http://code.djangoproject.com/svn/django/branches/multi-auth@3152 bcc190cf-cafb-0310-a4f2-bffc1f526a37

11 files changed, 200 insertions, 53 deletions

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index 9f5dc640da..d72e92b018 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -49,8 +49,8 @@ humanize
 ========
 
 A set of Django template filters useful for adding a "human touch" to data.
-To activate these filters, add ``'django.contrib.english'`` to your
-``INSTALLED_APPS`` setting. Once you've done that, use ``{% load english %}``
+To activate these filters, add ``'django.contrib.humanize'`` to your
+``INSTALLED_APPS`` setting. Once you've done that, use ``{% load humanize %}``
 in a template, and you'll have access to these filters:
 
 apnumber
diff --git a/docs/authentication.txt b/docs/authentication.txt
index c1a1f8494d..3edbc21f7a 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -355,8 +355,8 @@ Here's what ``django.contrib.auth.views.login`` does::
       form.
 
 It's your responsibility to provide the login form in a template called
-``registration/login.html``. This template gets passed three template context
-variables:
+``registration/login.html`` by default. This template gets passed three
+template context variables:
 
     * ``form``: A ``FormWrapper`` object representing the login form. See the
       `forms documentation`_ for more on ``FormWrapper`` objects.
@@ -365,6 +365,13 @@ variables:
     * ``site_name``: The name of the current ``Site``, according to the
       ``SITE_ID`` setting. See the `site framework docs`_.
 
+If you'd prefer not to call the template ``registration/login.html``, you can
+pass the ``template_name`` parameter via the extra arguments to the view in
+your URLconf. For example, this URLconf line would use ``myapp/login.html``
+instead::
+
+    (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),
+
 Here's a sample ``registration/login.html`` template you can use as a starting
 point. It assumes you have a ``base.html`` template that defines a ``content``
 block::
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 3624620609..5108949184 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -559,7 +559,7 @@ following models::
         # ...
         hometown = models.ForeignKey(City)
 
-    class Book(meta.Model):
+    class Book(models.Model):
         # ...
         author = models.ForeignKey(Person)
 
@@ -705,6 +705,64 @@ The ``DoesNotExist`` exception inherits from
     except ObjectDoesNotExist:
         print "Either the entry or blog doesn't exist."
 
+``get_or_create(**kwargs)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A convenience method for looking up an object with the given kwargs, creating
+one if necessary.
+
+Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or
+created object and ``created`` is a boolean specifying whether a new object was
+created.
+
+This is meant as a shortcut to boilerplatish code and is mostly useful for
+data-import scripts. For example::
+
+    try:
+        obj = Person.objects.get(first_name='John', last_name='Lennon')
+    except Person.DoesNotExist:
+        obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))
+        obj.save()
+
+This pattern gets quite unwieldy as the number of fields in a model goes up.
+The above example can be rewritten using ``get_or_create()`` like so::
+
+    obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon',
+                      defaults={'birthday': date(1940, 10, 9)})
+
+Any keyword arguments passed to ``get_or_create()`` -- *except* an optional one
+called ``defaults`` -- will be used in a ``get()`` call. If an object is found,
+``get_or_create()`` returns a tuple of that object and ``False``. If an object
+is *not* found, ``get_or_create()`` will instantiate and save a new object,
+returning a tuple of the new object and ``True``. The new object will be
+created according to this algorithm::
+
+    defaults = kwargs.pop('defaults', {})
+    params = dict([(k, v) for k, v in kwargs.items() if '__' not in k])
+    params.update(defaults)
+    obj = self.model(**params)
+    obj.save()
+
+In English, that means start with any non-``'defaults'`` keyword argument that
+doesn't contain a double underscore (which would indicate a non-exact lookup).
+Then add the contents of ``defaults``, overriding any keys if necessary, and
+use the result as the keyword arguments to the model class.
+
+If you have a field named ``defaults`` and want to use it as an exact lookup in
+``get_or_create()``, just use ``'defaults__exact'``, like so::
+
+    Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
+
+Finally, a word on using ``get_or_create()`` in Django views. As mentioned
+earlier, ``get_or_create()`` is mostly useful in scripts that need to parse
+data and create new records if existing ones aren't available. But if you need
+to use ``get_or_create()`` in a view, please make sure to use it only in
+``POST`` requests unless you have a good reason not to. ``GET`` requests
+shouldn't have any effect on data; use ``POST`` whenever a request to a page
+has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
+
+.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
+
 ``count()``
 ~~~~~~~~~~~
 
diff --git a/docs/faq.txt b/docs/faq.txt
index a2c069f0ca..7238a0aef7 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -200,6 +200,23 @@ In the meantime, though, check out this `unofficial Django screencast`_.
 
 .. _unofficial Django screencast: http://www.throwingbeans.org/django_screencasts.html
 
+Is Django a content-management-system (CMS)?
+--------------------------------------------
+
+No, Django is not a CMS, or any sort of "turnkey product" in and of itself.
+It's a Web framework; it's a programming tool that lets you build Web sites.
+
+For example, it doesn't make much sense to compare Django to something like
+Drupal_, because Django is something you use to *create* things like Drupal.
+
+Of course, Django's automatic admin site is fantastic and timesaving -- but
+the admin site is one module of Django the framework. Furthermore, although
+Django has special conveniences for building "CMS-y" apps, that doesn't mean
+it's not just as appropriate for building "non-CMS-y" apps (whatever that
+means!).
+
+.. _Drupal: http://drupal.org/
+
 When will you release Django 1.0?
 ---------------------------------
 
@@ -222,7 +239,7 @@ How can I download the Django documentation to read it offline?
 ---------------------------------------------------------------
 
 The Django docs are available in the ``docs`` directory of each Django tarball
-release. These docs are in ReST (restructured text) format, and each text file
+release. These docs are in ReST (ReStructured Text) format, and each text file
 corresponds to a Web page on the official Django site.
 
 Because the documentation is `stored in revision control`_, you can browse
@@ -297,13 +314,16 @@ as long as that server has WSGI_ hooks. See the `server arrangements wiki page`_
 How do I install mod_python on Windows?
 ---------------------------------------
 
-    * For Python 2.4, check out this `guide to mod_python & Python 2.3`_.
+    * For Python 2.4, grab mod_python from `win32 build of mod_python for
+      Python 2.4`_.
+    * For Python 2.4, check out this `Django on Windows howto`_.
     * For Python 2.3, grab mod_python from http://www.modpython.org/ and read
       `Running mod_python on Apache on Windows2000`_.
     * Also, try this (not Windows-specific) `guide to getting mod_python
       working`_.
 
-.. _`guide to mod_python & Python 2.3`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24
+.. _`win32 build of mod_python for Python 2.4`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24
+.. _`Django on Windows howto`: http://thinkhole.org/wp/2006/04/03/django-on-windows-howto/
 .. _`Running mod_python on Apache on Windows2000`: http://groups-beta.google.com/group/comp.lang.python/msg/139af8c83a5a9d4f
 .. _`guide to getting mod_python working`: http://www.dscpl.com.au/articles/modpython-001.html
 
@@ -388,19 +408,12 @@ Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
 If I make changes to a model, how do I update the database?
 -----------------------------------------------------------
 
-If you don't mind clearing data, just pipe the output of the appropriate
-``django-admin.py sqlreset`` command into your database's command-line utility.
-For example::
-
-    django-admin.py sqlreset appname | psql dbname
+If you don't mind clearing data, your project's ``manage.py`` utility has an
+option to reset the SQL for a particular application::
 
-That "psql" assumes you're using PostgreSQL. If you're using MySQL, use the
-appropriate command-line utility, ``mysql``.
+    manage.py reset appname
 
-``django-admin.py sqlreset`` outputs SQL that clears the app's database
-table(s) and creates new ones. The above command uses a Unix pipe to send the
-SQL directly to the PostgreSQL command-line utility, which accepts SQL as
-input.
+This drops any tables associated with ``appname`` and recreates them.
 
 If you do care about deleting data, you'll have to execute the ``ALTER TABLE``
 statements manually in your database. That's the way we've always done it,
diff --git a/docs/forms.txt b/docs/forms.txt
index 2f8a3106fc..5026bc1bab 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -15,6 +15,8 @@ We'll take a top-down approach to examining Django's form validation framework,
 because much of the time you won't need to use the lower-level APIs. Throughout
 this document, we'll be working with the following model, a "place" object::
 
+    from django.db import models
+
     PLACE_TYPES = (
         (1, 'Bar'),
         (2, 'Restaurant'),
@@ -22,13 +24,13 @@ this document, we'll be working with the following model, a "place" object::
         (4, 'Secret Hideout'),
     )
 
-    class Place(meta.Model):
-        name = meta.CharField(maxlength=100)
-        address = meta.CharField(maxlength=100, blank=True)
-        city = meta.CharField(maxlength=50, blank=True)
-        state = meta.USStateField()
-        zip_code = meta.CharField(maxlength=5, blank=True)
-        place_type = meta.IntegerField(choices=PLACE_TYPES)
+    class Place(models.Model):
+        name = models.CharField(maxlength=100)
+        address = models.CharField(maxlength=100, blank=True)
+        city = models.CharField(maxlength=50, blank=True)
+        state = models.USStateField()
+        zip_code = models.CharField(maxlength=5, blank=True)
+        place_type = models.IntegerField(choices=PLACE_TYPES)
 
         class Admin:
             pass
diff --git a/docs/i18n.txt b/docs/i18n.txt
index e6660f939d..1220ea95b3 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -133,8 +133,8 @@ For example, to translate a model's ``help_text``, do the following::
 
     from django.utils.translation import gettext_lazy
 
-    class MyThing(meta.Model):
-        name = meta.CharField(help_text=gettext_lazy('This is the help text'))
+    class MyThing(models.Model):
+        name = models.CharField(help_text=gettext_lazy('This is the help text'))
 
 In this example, ``gettext_lazy()`` stores a lazy reference to the string --
 not the actual translation. The translation itself will be done when the string
@@ -145,8 +145,8 @@ If you don't like the verbose name ``gettext_lazy``, you can just alias it as
 
     from django.utils.translation import gettext_lazy as _
 
-    class MyThing(meta.Model):
-        name = meta.CharField(help_text=_('This is the help text'))
+    class MyThing(models.Model):
+        name = models.CharField(help_text=_('This is the help text'))
 
 Always use lazy translations in `Django models`_. And it's a good idea to add
 translations for the field names and table names, too. This means writing
@@ -155,8 +155,8 @@ class, though::
 
     from django.utils.translation import gettext_lazy as _
 
-    class MyThing(meta.Model):
-        name = meta.CharField(_('name'), help_text=_('This is the help text'))
+    class MyThing(models.Model):
+        name = models.CharField(_('name'), help_text=_('This is the help text'))
         class Meta:
             verbose_name = _('my thing')
             verbose_name_plural = _('mythings')
@@ -230,12 +230,17 @@ Each ``RequestContext`` has access to two translation-specific variables:
       language code and the second is the language name (in that language).
     * ``LANGUAGE_CODE`` is the current user's preferred language, as a string.
       Example: ``en-us``. (See "How language preference is discovered", below.)
+    * ``LANGUAGE_BIDI`` is the current language's direction. If True, it's a
+      right-to-left language, e.g: Hebrew, Arabic. If False it's a
+      left-to-right language, e.g: English, French, German etc.
+
 
 If you don't use the ``RequestContext`` extension, you can get those values with
-two tags::
+three tags::
 
     {% get_current_language as LANGUAGE_CODE %}
     {% get_available_languages as LANGUAGES %}
+    {% get_current_language_bidi as LANGUAGE_BIDI %}
 
 These tags also require a ``{% load i18n %}``.
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index c6707a691b..0dc98416a3 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -445,7 +445,8 @@ empty value. If a field has ``blank=False``, the field will be required.
 ``choices``
 ~~~~~~~~~~~
 
-A list of 2-tuples to use as choices for this field.
+An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
+field.
 
 If this is given, Django's admin will use a select box instead of the
 standard text field and will limit choices to the choices given.
@@ -481,6 +482,12 @@ or outside your model class altogether::
     class Foo(models.Model):
         gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
 
+Finally, note that choices can be any iterable object -- not necessarily a
+list or tuple. This lets you construct choices dynamically. But if you find
+yourself hacking ``choices`` to be dynamic, you're probably better off using
+a proper database table with a ``ForeignKey``. ``choices`` is meant for static
+data that doesn't change much, if ever.
+
 ``core``
 ~~~~~~~~
 
@@ -1627,10 +1634,10 @@ to happen whenever you save an object. For example::
         name = models.CharField(maxlength=100)
         tagline = models.TextField()
 
-    def save(self):
-        do_something()
-        super(Blog, self).save() # Call the "real" save() method.
-        do_something_else()
+        def save(self):
+            do_something()
+            super(Blog, self).save() # Call the "real" save() method.
+            do_something_else()
 
 You can also prevent saving::
 
@@ -1638,11 +1645,11 @@ You can also prevent saving::
         name = models.CharField(maxlength=100)
         tagline = models.TextField()
 
-    def save(self):
-        if self.name == "Yoko Ono's blog":
-            return # Yoko shall never have her own blog!
-        else:
-            super(Blog, self).save() # Call the "real" save() method.
+        def save(self):
+            if self.name == "Yoko Ono's blog":
+                return # Yoko shall never have her own blog!
+            else:
+                super(Blog, self).save() # Call the "real" save() method.
 
 .. _database API docs: http://www.djangoproject.com/documentation/db_api/
 
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 33e5ef4d84..4939cac76f 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -400,6 +400,10 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in
 ``HttpResponseForbidden``
     Acts just like ``HttpResponse`` but uses a 403 status code.
 
+``HttpResponseNotAllowed``
+    Like ``HttpResponse``, but uses a 405 status code. Takes a single,
+    required argument: a list of permitted methods (e.g. ``['GET', 'POST']``).
+
 ``HttpResponseGone``
     Acts just like ``HttpResponse`` but uses a 410 status code.
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index b7b0a9047b..4f77c4ff21 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -439,6 +439,23 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
 
         author_link = 'http://www.example.com/' # Hard-coded author URL.
 
+        # CATEGORIES -- One of the following three is optional. The framework
+        # looks for them in this order. In each case, the method/attribute
+        # should return an iterable object that returns strings.
+
+        def categories(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            categories as iterable over strings.
+            """
+
+        def categories(self):
+            """
+            Returns the feed's categories as iterable over strings.
+            """
+
+        categories = ("python", "django") # Hard-coded list of categories.
+
         # ITEMS -- One of the following three is required. The framework looks
         # for them in this order.
 
@@ -602,6 +619,25 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
 
         item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
 
+        # ITEM CATEGORIES -- It's optional to use one of these three. This is
+        # a hook that specifies how to get the list of categories for a given
+        # item. In each case, the method/attribute should return an iterable
+        # object that returns strings.
+
+        def item_categories(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            categories.
+            """
+
+        def item_categories(self):
+            """
+            Returns the categories for every item in the feed.
+            """
+
+        item_categories = ("python", "django") # Hard-coded categories.
+
+
 The low-level framework
 =======================
 
diff --git a/docs/templates.txt b/docs/templates.txt
index c191b409f4..5f397c5a60 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -454,8 +454,12 @@ displayed by the ``{{ athlete_list|length }}`` variable.
 As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
 will be displayed if the test fails.
 
-``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
-a given variable::
+``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or
+to negate a given variable::
+
+    {% if athlete_list and coach_list %}
+        Both athletes and coaches are available.
+    {% endif %}
 
     {% if not athlete_list %}
         There are no athletes.
@@ -468,16 +472,24 @@ a given variable::
     {% if not athlete_list or coach_list %}
         There are no athletes or there are some coaches (OK, so
         writing English translations of boolean logic sounds
-        stupid; it's not my fault).
+        stupid; it's not our fault).
+    {% endif %}
+
+    {% if athlete_list and not coach_list %}
+        There are some athletes and absolutely no coaches.
     {% endif %}
 
-For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
-tags instead::
+``if`` tags don't allow ``and`` and ``or`` clauses within the same tag, because
+the order of logic would be ambiguous. For example, this is invalid::
+
+    {% if athlete_list and coach_list or cheerleader_list %}
+
+If you need to combine ``and`` and ``or`` to do advanced logic, just use nested
+``if`` tags. For example::
 
     {% if athlete_list %}
-        {% if coach_list %}
-            Number of athletes: {{ athlete_list|length }}.
-            Number of coaches: {{ coach_list|length }}.
+        {% if coach_list or cheerleader_list %}
+            We have athletes, and either coaches or cheerleaders!
         {% endif %}
     {% endif %}
 
@@ -754,6 +766,8 @@ The argument tells which template bit to output:
     ``closeblock``      ``%}``
     ``openvariable``    ``{{``
     ``closevariable``   ``}}``
+    ``openbrace``       ``{``
+    ``closebrace``      ``}``
     ==================  =======
 
 widthratio
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index dea5bcbee6..5e3038ebb4 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -502,12 +502,13 @@ Although the Django template language comes with several default tags and
 filters, you might want to write your own. It's easy to do.
 
 First, create a ``templatetags`` package in the appropriate Django app's
-package. It should be on the same level as ``models``, ``views.py``, etc. For
+package. It should be on the same level as ``models.py``, ``views.py``, etc. For
 example::
 
     polls/
-        models/
+        models.py
         templatetags/
+        views.py
 
 Add two files to the ``templatetags`` package: an ``__init__.py`` file and a
 file that will contain your custom tag/filter definitions. The name of the