Merge branch 'master' into schema-alteration

11 files changed, 242 insertions, 63 deletions

diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt
index 3ba7c38c43..ee0bf0f225 100644
--- a/docs/ref/class-based-views/base.txt
+++ b/docs/ref/class-based-views/base.txt
@@ -9,7 +9,7 @@ required for projects, in which case there are Mixins and Generic class-based
 views.
 
 Many of Django's built-in class-based views inherit from other class-based
-views or various mixins. Because this inheritence chain is very important, the
+views or various mixins. Because this inheritance chain is very important, the
 ancestor classes are  documented under the section title of **Ancestors (MRO)**.
 MRO is an acronym for Method Resolution Order.
 
diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt
index b3e26eca48..394d078e5b 100644
--- a/docs/ref/contrib/admin/admindocs.txt
+++ b/docs/ref/contrib/admin/admindocs.txt
@@ -57,9 +57,10 @@ Model reference
 ===============
 
 The **models** section of the ``admindocs`` page describes each model in the
-system along with all the fields and methods available on it. Relationships to
-other models appear as hyperlinks. Descriptions are pulled from ``help_text``
-attributes on fields or from docstrings on model methods.
+system along with all the fields and methods (without any arguments) available
+on it. While model properties don't have any arguments, they are not listed.
+Relationships to other models appear as hyperlinks. Descriptions are pulled
+from ``help_text`` attributes on fields or from docstrings on model methods.
 
 A model with useful documentation might look like this::
 
diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt
new file mode 100644
index 0000000000..d0c671958f
--- /dev/null
+++ b/docs/ref/contrib/gis/forms-api.txt
@@ -0,0 +1,165 @@
+.. _ref-gis-forms-api:
+
+===================
+GeoDjango Forms API
+===================
+
+.. module:: django.contrib.gis.forms
+   :synopsis: GeoDjango forms API.
+
+.. versionadded:: 1.6
+
+GeoDjango provides some specialized form fields and widgets in order to visually 
+display and edit geolocalized data on a map. By default, they use
+`OpenLayers`_-powered maps, with a base WMS layer provided by `Metacarta`_.
+
+.. _OpenLayers: http://openlayers.org/
+.. _Metacarta: http://metacarta.com/
+
+Field arguments
+===============
+In addition to the regular :ref:`form field arguments <core-field-arguments>`,
+GeoDjango form fields take the following optional arguments.
+
+``srid``
+~~~~~~~~
+
+.. attribute:: Field.srid
+
+    This is the SRID code that the field value should be transformed to. For
+    example, if the map widget SRID is different from the SRID more generally
+    used by your application or database, the field will automatically convert
+    input values into that SRID.
+
+``geom_type``
+~~~~~~~~~~~~~
+
+.. attribute:: Field.geom_type
+
+    You generally shouldn't have to set or change that attribute which should
+    be setup depending on the field class. It matches the OpenGIS standard
+    geometry name.
+
+Form field classes
+==================
+
+``GeometryField``
+~~~~~~~~~~~~~~~~~
+
+.. class:: GeometryField
+
+``PointField``
+~~~~~~~~~~~~~~
+
+.. class:: PointField
+
+``LineStringField``
+~~~~~~~~~~~~~~~~~~~
+
+.. class:: LineStringField
+
+``PolygonField``
+~~~~~~~~~~~~~~~~
+
+.. class:: PolygonField
+
+``MultiPointField``
+~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultiPointField
+
+``MultiLineStringField``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultiLineStringField
+
+``MultiPolygonField``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultiPolygonField
+
+``GeometryCollectionField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: GeometryCollectionField
+
+Form widgets
+============
+
+.. module:: django.contrib.gis.widgets
+   :synopsis: GeoDjango widgets API.
+
+GeoDjango form widgets allow you to display and edit geographic data on a
+visual map.
+Note that none of the currently available widgets supports 3D geometries, hence
+geometry fields will fallback using a simple ``Textarea`` widget for such data.
+
+Widget attributes
+~~~~~~~~~~~~~~~~~
+
+GeoDjango widgets are template-based, so their attributes are mostly different
+from other Django widget attributes.
+
+
+.. attribute:: BaseGeometryWidget.geom_type
+
+    The OpenGIS geometry type, generally set by the form field.
+
+.. attribute:: BaseGeometryWidget.map_height
+.. attribute:: BaseGeometryWidget.map_width
+
+    Height and width of the widget map (default is 400x600).
+
+.. attribute:: BaseGeometryWidget.map_srid
+
+    SRID code used by the map (default is 4326).
+
+.. attribute:: BaseGeometryWidget.display_wkt
+
+    Boolean value specifying if a textarea input showing the WKT representation
+    of the current geometry is visible, mainly for debugging purposes (default
+    is ``False``).
+
+.. attribute:: BaseGeometryWidget.supports_3d
+
+    Indicates if the widget supports edition of 3D data (default is ``False``).
+
+.. attribute:: BaseGeometryWidget.template_name
+
+    The template used to render the map widget.
+
+You can pass widget attributes in the same manner that for any other Django
+widget. For example::
+
+    from django.contrib.gis import forms
+
+    class MyGeoForm(forms.Form):
+        point = forms.PointField(widget=
+            forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500}))
+
+Widget classes
+~~~~~~~~~~~~~~
+
+``BaseGeometryWidget``
+
+.. class:: BaseGeometryWidget
+
+    This is an abstract base widget containing the logic needed by subclasses.
+    You cannot directly use this widget for a geometry field.
+    Note that the rendering of GeoDjango widgets is based on a template,
+    identified by the :attr:`template_name` class attribute.
+
+``OpenLayersWidget``
+
+.. class:: OpenLayersWidget
+
+    This is the default widget used by all GeoDjango form fields.
+    ``template_name`` is ``gis/openlayers.html``.
+
+``OSMWidget``
+
+.. class:: OSMWidget
+
+    This widget uses an OpenStreetMap base layer (Mapnik) to display geographic
+    objects on.
+    ``template_name`` is ``gis/openlayers-osm.html``.
diff --git a/docs/ref/contrib/gis/index.txt b/docs/ref/contrib/gis/index.txt
index 6a1402bfab..c533aa459d 100644
--- a/docs/ref/contrib/gis/index.txt
+++ b/docs/ref/contrib/gis/index.txt
@@ -18,6 +18,7 @@ of spatially enabled data.
    install/index
    model-api
    db-api
+   forms-api
    geoquerysets
    measure
    geos
diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt
index 2a6dcef46f..fca6675345 100644
--- a/docs/ref/contrib/gis/testing.txt
+++ b/docs/ref/contrib/gis/testing.txt
@@ -134,57 +134,14 @@ your settings::
 GeoDjango tests
 ===============
 
-GeoDjango's test suite may be run in one of two ways, either by itself or
-with the rest of :ref:`Django's unit tests <running-unit-tests>`.
+To have the GeoDjango tests executed when :ref:`running the Django test suite
+<running-unit-tests>` with ``runtests.py`` all of the databases in the settings
+file must be using one of the :ref:`spatial database backends
+<spatial-backends>`.
 
-Run only GeoDjango tests
-------------------------
-
-.. class:: django.contrib.gis.tests.GeoDjangoTestSuiteRunner
-
-To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`
-setting must be changed to use the
-:class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`::
-
-    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
 
 Example
-^^^^^^^
-
-First, you'll need a bare-bones settings file, like below, that is
-customized with your spatial database name and user::
-
-    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
-
-    DATABASES = {
-        'default': {
-            'ENGINE': 'django.contrib.gis.db.backends.postgis',
-            'NAME': 'a_spatial_database',
-            'USER': 'db_user'
-        }
-    }
-
-Assuming the above is in a file called ``postgis.py`` that is in the
-the same directory as ``manage.py`` of your Django project, then
-you may run the tests with the following command::
-
-    $ python manage.py test --settings=postgis
-
-Run with ``runtests.py``
-------------------------
-
-To have the GeoDjango tests executed when
-:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
-all of the databases in the settings file must be using one of the
-:ref:`spatial database backends <spatial-backends>`.
-
-.. warning::
-
-    Do not change the :setting:`TEST_RUNNER` setting
-    when running the GeoDjango tests with ``runtests.py``.
-
-Example
-^^^^^^^
+-------
 
 The following is an example bare-bones settings file with spatial backends
 that can be used to run the entire Django test suite, including those
@@ -208,3 +165,7 @@ directory as ``runtests.py``, then all Django and GeoDjango tests would
 be performed when executing the command::
 
     $ ./runtests.py --settings=postgis
+
+To run only the GeoDjango test suite, specify ``django.contrib.gis``::
+
+    $ ./runtests.py --settings=postgis django.contrib.gis
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index ec49705add..2f2880679c 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -373,7 +373,46 @@ application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 :setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
 
 When fixture files are processed, the data is saved to the database as is.
-Model defined ``save`` methods and ``pre_save`` signals are not called.
+Model defined :meth:`~django.db.models.Model.save` methods are not called, and
+any :data:`~django.db.models.signals.pre_save` or
+:data:`~django.db.models.signals.post_save` signals will be called with
+``raw=True`` since the instance only contains attributes that are local to the
+model. You may, for example, want to disable handlers that access
+related fields that aren't present during fixture loading and would otherwise
+raise an exception::
+
+    from django.db.models.signals import post_save
+    from .models import MyModel
+
+    def my_handler(**kwargs):
+        # disable the handler during fixture loading
+        if kwargs['raw']:
+            return
+        ...
+
+    post_save.connect(my_handler, sender=MyModel)
+
+You could also write a simple decorator to encapsulate this logic::
+
+    from functools import wraps
+
+    def disable_for_loaddata(signal_handler):
+        """
+        Decorator that turns off signal handlers when loading fixture data.
+        """
+        @wraps(signal_handler)
+        def wrapper(*args, **kwargs):
+            if kwargs['raw']:
+                return
+            signal_handler(*args, **kwargs)
+        return wrapper
+
+    @disable_for_loaddata
+    def my_handler(**kwargs):
+        ...
+
+Just be aware that this logic will disable the signals whenever fixtures are
+deserialized, not just during ``loaddata``.
 
 Note that the order in which fixture files are processed is undefined. However,
 all fixture data is installed as a single transaction, so data in
diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 29f889445d..8e1a4b34d1 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -30,6 +30,8 @@ exception or returns the clean value::
     ...
     ValidationError: [u'Enter a valid email address.']
 
+.. _core-field-arguments:
+
 Core field arguments
 --------------------
 
@@ -608,19 +610,21 @@ For each field, we describe the default widget used if you don't specify
     * Normalizes to: An ``UploadedFile`` object that wraps the file content
       and file name into a single object.
     * Validates that file data has been bound to the form, and that the
-      file is of an image format understood by PIL.
+      file is of an image format understood by Pillow/PIL.
     * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
       ``invalid_image``
 
-    Using an ``ImageField`` requires that the `Python Imaging Library`_ (PIL)
-    is installed and supports the image formats you use. If you encounter a
-    ``corrupt image`` error when you upload an image, it usually means PIL
+    Using an ``ImageField`` requires that either `Pillow`_ (recommended) or the
+    `Python Imaging Library`_ (PIL) are installed and supports the image
+    formats you use. If you encounter a ``corrupt image`` error when you
+    upload an image, it usually means either Pillow or PIL
     doesn't understand its format. To fix this, install the appropriate
-    library and reinstall PIL.
+    library and reinstall Pillow or PIL.
 
     When you use an ``ImageField`` on a form, you must also remember to
     :ref:`bind the file data to the form <binding-uploaded-files>`.
 
+.. _Pillow: http://python-imaging.github.io/Pillow/
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 
 ``IntegerField``
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index d322904ec9..99ba78cb09 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -287,6 +287,9 @@ For example, if you have a field ``title`` that has
 ``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
 records with the same ``title`` and ``pub_date``.
 
+Note that if you set this to point to a :class:`DateTimeField`, only the date
+portion of the field will be considered.
+
 This is enforced by model validation but not at the database level.
 
 ``unique_for_month``
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index d27214a66c..ffada19082 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -328,7 +328,7 @@ Use the ``reverse()`` method to reverse the order in which a queryset's
 elements are returned. Calling ``reverse()`` a second time restores the
 ordering back to the normal direction.
 
-To retrieve the ''last'' five items in a queryset, you could do this::
+To retrieve the "last" five items in a queryset, you could do this::
 
     my_queryset.reverse()[:5]
 
@@ -1486,7 +1486,7 @@ internally so that repeated evaluations do not result in additional queries. In
 contrast, ``iterator()`` will read results directly, without doing any caching
 at the ``QuerySet`` level (internally, the default iterator calls ``iterator()``
 and caches the return value). For a ``QuerySet`` which returns a large number of
-objects that you only need to access once, this can results in better
+objects that you only need to access once, this can result in better
 performance and a significant reduction in memory.
 
 Note that using ``iterator()`` on a ``QuerySet`` which has already been
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 04b42aeeb2..eb470cdd14 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1725,11 +1725,16 @@ misspelled) variables. See :ref:`invalid-template-variables`..
 TEST_RUNNER
 -----------
 
-Default: ``'django.test.simple.DjangoTestSuiteRunner'``
+Default: ``'django.test.runner.DiscoverRunner'``
 
 The name of the class to use for starting the test suite. See
 :ref:`other-testing-frameworks`.
 
+.. versionchanged:: 1.6
+
+    Previously the default ``TEST_RUNNER`` was
+    ``django.test.simple.DjangoTestSuiteRunner``.
+
 .. setting:: THOUSAND_SEPARATOR
 
 THOUSAND_SEPARATOR
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index a7d5b6690e..14ae9aa9b8 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -659,11 +659,11 @@ Functions for working with Python modules.
     wrong. For example::
 
         from django.utils.module_loading import import_by_path
-        import_by_path = import_by_path('django.utils.module_loading.import_by_path')
+        ImproperlyConfigured = import_by_path('django.core.exceptions.ImproperlyConfigured')
 
     is equivalent to::
 
-        from django.utils.module_loading import import_by_path
+        from django.core.exceptions import ImproperlyConfigured
 
 ``django.utils.safestring``
 ===========================