Fixed #13315, #13430 -- Recreated django.contrib.gis.db.backend mod…

…ule with `SpatialBackend` alias and added `Adaptor` alias for backwards-compatibility purposes; added GeoDjango 1.2 backwards-incompatibility documentation and release notes; added a section in the docs about how MySQL is a crippled spatial database; updated versions in install docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13097 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/contrib/gis/db/backend/__init__.py

@@ -0,0 +1,24 @@
+from django.db import connection
+
+if hasattr(connection.ops, 'spatial_version'):
+    from warnings import warn
+    warn('The `django.contrib.gis.db.backend` module was refactored and '
+         'renamed to `django.contrib.gis.db.backends` in 1.2.  '
+         'All functionality of `SpatialBackend` '
+         'has been moved to the `ops` attribute of the spatial database '
+         'backend.  A `SpatialBackend` alias is provided here for '
+         'backwards-compatibility, but will be removed in 1.3.')
+    SpatialBackend = connection.ops
+
+from django.db import connection
+
+if hasattr(connection.ops, 'spatial_version'):
+    from warnings import warn
+    warn('The `django.contrib.gis.db.backend` module was refactored and '
+         'renamed to `django.contrib.gis.db.backends` in 1.2.  '
+         'All functionality of `SpatialBackend` '
+         'has been moved to the `ops` attribute of the spatial database '
+         'backend.  A `SpatialBackend` alias is provided here for '
+         'backwards-compatibility, but will be removed in 1.3.')
+    SpatialBackend = connection.ops
+

django/contrib/gis/db/backends/mysql/operations.py

@@ -13,6 +13,7 @@ class MySQLOperations(DatabaseOperations, BaseSpatialOperations):
     from_text = 'GeomFromText'
 
     Adapter = WKTAdapter
+    Adaptor = Adapter # Backwards-compatibility alias.
 
     geometry_functions = {
         'bbcontains' : 'MBRContains', # For consistency w/PostGIS API

django/contrib/gis/db/backends/oracle/models.py

@@ -18,7 +18,6 @@ class GeometryColumns(models.Model):
     srid = models.IntegerField(primary_key=True)
     # TODO: Add support for `diminfo` column (type MDSYS.SDO_DIM_ARRAY).
     class Meta:
-        app_label = 'gis'
         db_table = 'USER_SDO_GEOM_METADATA'
         managed = False
 
@@ -54,7 +53,6 @@ class SpatialRefSys(models.Model, SpatialRefSysMixin):
     objects = models.GeoManager()
 
     class Meta:
-        app_label = 'gis'
         db_table = 'CS_SRS'
         managed = False
 

django/contrib/gis/db/backends/oracle/operations.py

@@ -75,6 +75,7 @@ class OracleOperations(DatabaseOperations, BaseSpatialOperations):
     valid_aggregates = dict([(a, None) for a in ('Union', 'Extent')])
 
     Adapter = OracleSpatialAdapter
+    Adaptor = Adapter # Backwards-compatibility alias.
 
     area = 'SDO_GEOM.SDO_AREA'
     gml= 'SDO_UTIL.TO_GMLGEOMETRY'

django/contrib/gis/db/backends/postgis/models.py

@@ -18,7 +18,6 @@ class GeometryColumns(models.Model):
     type = models.CharField(max_length=30)
 
     class Meta:
-        app_label = 'gis'
         db_table = 'geometry_columns'
         managed = False
 
@@ -55,7 +54,6 @@ class SpatialRefSys(models.Model, SpatialRefSysMixin):
     proj4text = models.CharField(max_length=2048)
 
     class Meta:
-        app_label = 'gis'
         db_table = 'spatial_ref_sys'
         managed = False
 

django/contrib/gis/db/backends/postgis/operations.py

@@ -66,6 +66,7 @@ class PostGISOperations(DatabaseOperations, BaseSpatialOperations):
                              ('Collect', 'Extent', 'Extent3D', 'MakeLine', 'Union')])
 
     Adapter = PostGISAdapter
+    Adaptor = Adapter # Backwards-compatibility alias.
 
     def __init__(self, connection):
         super(PostGISOperations, self).__init__(connection)

django/contrib/gis/db/backends/spatialite/models.py

@@ -16,7 +16,6 @@ class GeometryColumns(models.Model):
     spatial_index_enabled = models.IntegerField()
 
     class Meta:
-        app_label = 'gis'
         db_table = 'geometry_columns'
         managed = False
 
@@ -57,6 +56,5 @@ def wkt(self):
         return SpatialReference(self.proj4text).wkt
 
     class Meta:
-        app_label = 'gis'
         db_table = 'spatial_ref_sys'
         managed = False

django/contrib/gis/db/backends/spatialite/operations.py

@@ -55,6 +55,7 @@ class SpatiaLiteOperations(DatabaseOperations, BaseSpatialOperations):
     valid_aggregates = dict([(k, None) for k in ('Extent', 'Union')])
 
     Adapter = SpatiaLiteAdapter
+    Adaptor = Adapter # Backwards-compatibility alias.
 
     area = 'Area'
     centroid = 'Centroid'

django/contrib/gis/models.py

@@ -0,0 +1,9 @@
+from django.db import connection
+
+if (hasattr(connection.ops, 'spatial_version') and
+    not connection.ops.mysql):
+    # Getting the `SpatialRefSys` and `GeometryColumns`
+    # models for the default spatial backend.  These
+    # aliases are provided for backwards-compatibility.
+    SpatialRefSys = connection.ops.spatial_ref_sys()
+    GeometryColumns = connection.ops.geometry_columns()

docs/ref/contrib/gis/db-api.txt

@@ -23,13 +23,16 @@ its functionality into full-fledged spatial database backends:
 * :mod:`django.contrib.gis.db.backends.oracle`
 * :mod:`django.contrib.gis.db.backends.spatialite`
 
-Backwards-Compatibility
------------------------
+Database Settings Backwards-Compatibility
+-----------------------------------------
 
-For those using the old database settings (e.g., the ``DATABASE_*`` settings)
-Django 1.2 will automatically use the appropriate spatial backend as long
-as :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`.  For
-example, if you have the following in your settings::
+In :ref:`Django 1.2 <releases-1.2>`, the way 
+to :ref:`specify databases <specifying-databases>` in your settings was changed.
+The old database settings format (e.g., the ``DATABASE_*`` settings)
+is backwards compatible with GeoDjango, and  will automatically use the
+appropriate spatial backend as long as :mod:`django.contrib.gis` is in
+your :setting:`INSTALLED_APPS`.  For example, if you have the following in
+your settings::
 
     DATABASE_ENGINE='postgresql_psycopg2'
 
@@ -41,9 +44,37 @@ example, if you have the following in your settings::
       ...
     )
 
-Then, :mod:`django.contrib.gis.db.backends.postgis` will automatically be used as your
+Then, :mod:`django.contrib.gis.db.backends.postgis` is automatically used as your
 spatial backend.
 
+.. _mysql-spatial-limitations:
+
+MySQL Spatial Limitations
+-------------------------
+
+MySQL's spatial extensions only support bounding box operations
+(what MySQL calls minimum bounding rectangles, or MBR).  Specifically,
+`MySQL does not conform to the OGC standard <http://dev.mysql.com/doc/refman/5.1/en/functions-that-test-spatial-relationships-between-geometries.html>`_:
+
+    Currently, MySQL does not implement these functions
+    [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``,
+    ``Touches``, ``Within``]
+    according to the specification.  Those that are implemented return
+    the same result as the corresponding MBR-based functions. 
+
+In other words, while spatial lookups such as :lookup:`contains <gis-contains>`
+are available in GeoDjango when using MySQL, the results returned are really
+equivalent to what would be returned when using :lookup:`bbcontains`
+on a different spatial backend.
+
+.. warning::
+
+    True spatial indexes (R-trees) are only supported with
+    MyISAM tables on MySQL. [#fnmysqlidx]_ In other words, when using
+    MySQL spatial extensions you have to choose between fast spatial
+    lookups and the integrity of your data -- MyISAM tables do
+    not support transactions or foreign key constraints.
+
 Creating and Saving Geographic Models
 =====================================
 Here is an example of how to create a geometry object (assuming the ``Zipcode``
@@ -307,4 +338,12 @@ Method                                PostGIS  Oracle  SpatiaLite
 .. [#fngeojson] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008).
 .. [#fndistsphere14] *See* `PostGIS 1.4 documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``.
 .. [#fndistsphere15] *See* `PostGIS 1.5 documentation <http://postgis.refractions.net/documentation/manual-1.5/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``.
-.. [#] MySQL only supports bounding box operations (known as minimum bounding rectangles, or MBR, in MySQL).  Thus, spatial lookups such as :lookup:`contains <gis-contains>` are really equivalent to :lookup:`bbcontains`.
+.. [#fnmysqlidx] *See* `Creating Spatial Indexes <http://dev.mysql.com/doc/refman/5.1/en/creating-spatial-indexes.html>`_
+   in the MySQL 5.1 Reference Manual:
+
+       For MyISAM tables, ``SPATIAL INDEX`` creates an R-tree index. For storage
+       engines that support nonspatial indexing of spatial columns, the engine
+       creates a B-tree index. A B-tree index on spatial values will be useful
+       for exact-value lookups, but not for range scans.
+
+.. [#] Refer :ref:`mysql-spatial-limitations` section for more details.

docs/ref/contrib/gis/install.txt

@@ -150,13 +150,13 @@ directly from Python using ctypes.
 First, download GEOS 3.2 from the refractions website and untar the source 
 archive::
 
-    $ wget http://download.osgeo.org/geos/geos-3.2.1.tar.bz2
-    $ tar xjf geos-3.2.1.tar.bz2
+    $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2
+    $ tar xjf geos-3.2.2.tar.bz2
 
 Next, change into the directory where GEOS was unpacked, run the configure 
 script, compile, and install::
 
-    $ cd geos-3.2.1
+    $ cd geos-3.2.2
     $ ./configure
     $ make
     $ sudo make install
@@ -273,9 +273,9 @@ supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
 
 First download the latest GDAL release version and untar the archive::
 
-    $ wget http://download.osgeo.org/gdal/gdal-1.7.1.tar.gz
-    $ tar xzf gdal-1.7.1.tar.gz
-    $ cd gdal-1.7.1
+    $ wget http://download.osgeo.org/gdal/gdal-1.7.2.tar.gz
+    $ tar xzf gdal-1.7.2.tar.gz
+    $ cd gdal-1.7.2
 
 Configure, make and install::
 
@@ -516,9 +516,9 @@ user.  For example, you can use the following to become the ``postgres`` user::
 
    The location *and* name of the PostGIS SQL files (e.g., from
    ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
-   PostGIS versions 1.3 and below use ``<sharedir>/contrib/lwpostgis.sql``, whereas
-   versions 1.4 and 1.5 use ``<sharedir>/contrib/postgis-1.4/postgis.sql`` and
-   ``<sharedir>/contrib/postgis-1.5/postgis.sql``, respectively.
+   PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
+   whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
+   version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
 
    The example below assumes PostGIS 1.5, thus you may need to modify
    ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific