Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #12930, #12832, #11538 -- Refactored and merged the GeoDjango d…

…ocumentation into the rest of the Django docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12856 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 459c71e3320b17bb4e0f3188baf7ca3ff1bd2260 1 parent 667ced2
Justin Bronn authored March 26, 2010
57  docs/ref/contrib/gis/admin.txt
... ...
@@ -0,0 +1,57 @@
  1
+.. _ref-gis-admin:
  2
+
  3
+======================
  4
+GeoDjango's admin site
  5
+======================
  6
+
  7
+.. module:: django.contrib.gis.admin
  8
+   :synopsis: GeoDjango's extensions to the admin site.
  9
+
  10
+
  11
+``GeoModelAdmin``
  12
+=================
  13
+
  14
+.. class:: GeoModelAdmin
  15
+
  16
+   .. attribute:: default_lon
  17
+
  18
+   The default center longitude.
  19
+
  20
+   .. attribute:: default_lat
  21
+
  22
+   The default center latitude.
  23
+
  24
+   .. attribute:: default_zoom
  25
+
  26
+   The default zoom level to use.  Defaults to 18.
  27
+
  28
+   .. attribute:: extra_js
  29
+
  30
+   Sequence of URLs to any extra JavaScript to include.
  31
+
  32
+   .. attribute:: map_template
  33
+
  34
+   Override the template used to generate the JavaScript slippy map.
  35
+   Default is ``'gis/admin/openlayers.html'``.
  36
+
  37
+   .. attribute:: map_width
  38
+
  39
+   Width of the map, in pixels.  Defaults to 600.
  40
+
  41
+   .. attribute:: map_height
  42
+
  43
+   Height of the map, in pixels.  Defaults to 400.
  44
+
  45
+   .. attribute:: openlayers_url
  46
+
  47
+   Link to the URL of the OpenLayers JavaScript.  Defaults to
  48
+   ``'http://openlayers.org/api/2.8/OpenLayers.js'``.
  49
+
  50
+``OSMGeoAdmin``
  51
+===============
  52
+
  53
+.. class:: OSMGeoAdmin
  54
+
  55
+   A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection
  56
+   with OpenStreetMap street data tiles.  See the :ref:`OSMGeoAdmin introduction <osmgeoadmin-intro>`
  57
+   in the tutorial for a usage example.
83  docs/ref/contrib/gis/commands.txt
... ...
@@ -0,0 +1,83 @@
  1
+.. ref-geodjango-admin:
  2
+
  3
+=============================
  4
+GeoDjango Management Commands
  5
+=============================
  6
+
  7
+inspectdb
  8
+=========
  9
+
  10
+.. describe:: django-admin.py inspectdb
  11
+
  12
+When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the
  13
+:djadmin:`inspectdb` management command is overridden with one from GeoDjango.
  14
+The overridden command is spatially-aware, and places geometry fields in the
  15
+auto-generated model definition, where appropriate.
  16
+
  17
+ogrinspect <data_source> <model_name>
  18
+=====================================
  19
+
  20
+.. django-admin:: ogrinspect
  21
+
  22
+The ``ogrinpsect`` management command will inspect the given OGR-compatible
  23
+:class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will
  24
+output a GeoDjango model with the given model name.  There's a detailed example
  25
+of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
  26
+
  27
+.. django-admin-option:: --blank <blank_field(s)>
  28
+
  29
+   Use a comma separated list of OGR field names to add the ``blank=True``
  30
+   keyword option to the field definition.  Set with ``true`` to apply
  31
+   to all applicable fields.
  32
+
  33
+.. django-admin-option:: --decimal <decimal_field(s)>
  34
+
  35
+   Use a comma separated list of OGR float fields to generate
  36
+   :class:`~django.db.models.DecimalField` instead of the default
  37
+   :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all
  38
+   OGR float fields.
  39
+
  40
+.. django-admin-option:: --geom-name <name>
  41
+
  42
+   Specifies the model attribute name to use for the geometry field.
  43
+   Defaults to ``'geom'``.
  44
+
  45
+.. django-admin-option:: --layer <layer>
  46
+
  47
+   The key for specifying which layer in the OGR
  48
+   :class:`~django.contrib.gis.gdal.DataSource` source to use.
  49
+   Defaults to 0 (the first layer). May be an integer or a string identifier
  50
+   for the :class:`~django.contrib.gis.gdal.Layer`.
  51
+
  52
+.. django-admin-option:: --mapping
  53
+
  54
+   Automatically generate a mapping dictionary for use with
  55
+   :class:`~django.contrib.gis.utils.LayerMapping`.
  56
+
  57
+.. django-admin-option:: --multi-geom
  58
+
  59
+   When generating the geometry field, treat it as a geometry collection.
  60
+   For example, if this setting is enabled then a
  61
+   :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed
  62
+   in the generated model rather than
  63
+   :class:`~django.contrib.gis.db.models.PolygonField`.
  64
+
  65
+.. django-admin-option:: --name-field <name_field>
  66
+
  67
+   Generates a ``__unicode__`` routine on the model that will return the
  68
+   the given field name.
  69
+
  70
+.. django-admin-option:: --no-imports
  71
+
  72
+   Suppresses the ``from django.contrib.gis.db import models`` import statement.
  73
+
  74
+.. django-admin-option:: --null <null_field(s)>
  75
+
  76
+   Use a comma separated list of OGR field names to add the ``null=True``
  77
+   keyword option to the field definition.  Set with ``true`` to apply to
  78
+   all applicable fields.
  79
+
  80
+.. django-admin-option:: --srid
  81
+   
  82
+   The SRID to use for the geometry field.  If not set, ``ogrinspect`` attempts
  83
+   to automatically determine of the SRID of the data source.
9  docs/ref/contrib/gis/create_template_postgis-1.3.sh
... ...
@@ -0,0 +1,9 @@
  1
+#!/usr/bin/env bash
  2
+POSTGIS_SQL_PATH=`pg_config --sharedir`
  3
+createdb -E UTF8 template_postgis # Create the template spatial database.
  4
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
  5
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
  6
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
  7
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
  8
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
  9
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
9  docs/ref/contrib/gis/create_template_postgis-1.4.sh
... ...
@@ -0,0 +1,9 @@
  1
+#!/usr/bin/env bash
  2
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.4
  3
+createdb -E UTF8 template_postgis # Create the template spatial database.
  4
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
  5
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
  6
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
  7
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
  8
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
  9
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
9  docs/ref/contrib/gis/create_template_postgis-1.5.sh
... ...
@@ -0,0 +1,9 @@
  1
+#!/usr/bin/env bash
  2
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
  3
+createdb -E UTF8 template_postgis # Create the template spatial database.
  4
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
  5
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
  6
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
  7
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
  8
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
  9
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
9  docs/ref/contrib/gis/create_template_postgis-debian.sh
... ...
@@ -0,0 +1,9 @@
  1
+#!/usr/bin/env bash
  2
+POSTGIS_SQL_PATH=/usr/share/postgresql-8.3-postgis
  3
+createdb -E UTF8 template_postgis # Create the template spatial database.
  4
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
  5
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
  6
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
  7
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
  8
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
  9
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
304  docs/ref/contrib/gis/db-api.txt
... ...
@@ -0,0 +1,304 @@
  1
+.. _ref-gis-db-api:
  2
+
  3
+======================
  4
+GeoDjango Database API
  5
+======================
  6
+
  7
+.. module:: django.contrib.gis.db.models
  8
+   :synopsis: GeoDjango's database API.
  9
+
  10
+.. _spatial-backends:
  11
+
  12
+Spatial Backends
  13
+================
  14
+
  15
+.. versionadded:: 1.2
  16
+
  17
+In Django 1.2, support for :ref:`multiple databases <topics-db-multi-db>` was
  18
+introduced.  In order to support multiple databases, GeoDjango has segregated
  19
+its functionality into full-fledged spatial database backends:
  20
+
  21
+* :mod:`django.contrib.gis.db.backends.postgis`
  22
+* :mod:`django.contrib.gis.db.backends.mysql`
  23
+* :mod:`django.contrib.gis.db.backends.oracle`
  24
+* :mod:`django.contrib.gis.db.backends.spatialite`
  25
+
  26
+Backwards-Compatibility
  27
+-----------------------
  28
+
  29
+For those using the old database settings (e.g., the ``DATABASE_*`` settings)
  30
+Django 1.2 will automatically use the appropriate spatial backend as long
  31
+as :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`.  For
  32
+example, if you have the following in your settings::
  33
+
  34
+    DATABASE_ENGINE='postgresql_psycopg2'
  35
+
  36
+    ...
  37
+
  38
+    INSTALLED_APPS = (
  39
+      ...
  40
+      'django.contrib.gis',
  41
+      ...
  42
+    )
  43
+
  44
+Then, :mod:`django.contrib.gis.db.backends.postgis` will automatically be used as your
  45
+spatial backend.
  46
+
  47
+Creating and Saving Geographic Models
  48
+=====================================
  49
+Here is an example of how to create a geometry object (assuming the ``Zipcode``
  50
+model)::
  51
+
  52
+    >>> from zipcode.models import Zipcode
  53
+    >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
  54
+    >>> z.save()
  55
+
  56
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models::
  57
+
  58
+    >>> from django.contrib.gis.geos import GEOSGeometry
  59
+    >>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
  60
+    >>> z = Zipcode(code=77096, poly=poly)
  61
+    >>> z.save()
  62
+
  63
+Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a
  64
+different SRID value) than that of the field, then it will be implicitly 
  65
+transformed into the SRID of the model's field, using the spatial database's 
  66
+transform procedure::
  67
+
  68
+    >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084)  # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
  69
+    >>> z = Zipcode(code=78212, poly=poly_3084)
  70
+    >>> z.save()
  71
+    >>> from django.db import connection
  72
+    >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True)
  73
+    INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
  74
+
  75
+Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT
  76
+(Well Known Text [#fnwkt]_), HEXEWKB (PostGIS specific -- a WKB geometry in
  77
+hexadecimal [#fnewkb]_), and GeoJSON [#fngeojson]_ (requires GDAL). Essentially,
  78
+if the input is not a ``GEOSGeometry`` object, the geometry field will attempt to
  79
+create a ``GEOSGeometry`` instance from the input.
  80
+
  81
+For more information creating :class:`~django.contrib.gis.geos.GEOSGeometry`
  82
+objects, refer to the :ref:`GEOS tutorial <geos-tutorial>`.
  83
+
  84
+.. _spatial-lookups-intro:
  85
+
  86
+Spatial Lookups
  87
+===============
  88
+
  89
+GeoDjango's lookup types may be used with any manager method like
  90
+``filter()``, ``exclude()``, etc.  However, the lookup types unique to
  91
+GeoDjango are only available on geometry fields.
  92
+Filters on 'normal' fields (e.g. :class:`~django.db.models.CharField`)
  93
+may be chained with those on geographic fields.  Thus, geographic queries
  94
+take the following general form (assuming  the ``Zipcode`` model used in the
  95
+:ref:`ref-gis-model-api`)::
  96
+
  97
+    >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
  98
+    >>> qs = Zipcode.objects.exclude(...)
  99
+
  100
+For example::
  101
+
  102
+    >>> qs = Zipcode.objects.filter(poly__contains=pnt)
  103
+
  104
+In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>`
  105
+is the spatial lookup type, and ``pnt`` is the parameter (which may be a 
  106
+:class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of
  107
+GeoJSON , WKT, or HEXEWKB).
  108
+
  109
+A complete reference can be found in the :ref:`spatial lookup reference 
  110
+<spatial-lookups>`.
  111
+
  112
+.. note::
  113
+
  114
+    GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a 
  115
+    subclass of :class:`~django.db.models.QuerySet`.  The 
  116
+    :class:`GeoManager` instance attached to your model is what
  117
+    enables use of :class:`GeoQuerySet`.
  118
+
  119
+.. _distance-queries:
  120
+
  121
+Distance Queries
  122
+================
  123
+
  124
+Introduction
  125
+------------
  126
+Distance calculations with spatial data is tricky because, unfortunately,
  127
+the Earth is not flat.  Some distance queries with fields in a geographic
  128
+coordinate system may have to be expressed differently because of 
  129
+limitations in PostGIS.  Please see the :ref:`selecting-an-srid` section 
  130
+in the :ref:`ref-gis-model-api` documentation for more details.
  131
+
  132
+.. _distance-lookups-intro:
  133
+
  134
+Distance Lookups
  135
+----------------
  136
+*Availability*: PostGIS, Oracle, SpatiaLite
  137
+
  138
+The following distance lookups are available:
  139
+
  140
+* :lookup:`distance_lt`
  141
+* :lookup:`distance_lte`
  142
+* :lookup:`distance_gt`
  143
+* :lookup:`distance_gte`
  144
+* :lookup:`dwithin`
  145
+
  146
+.. note::
  147
+
  148
+    For *measuring*, rather than querying on distances, use the
  149
+    :meth:`GeoQuerySet.distance` method.
  150
+
  151
+Distance lookups take a tuple parameter comprising:
  152
+
  153
+#. A geometry to base calculations from; and 
  154
+#. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance.
  155
+
  156
+If a :class:`~django.contrib.gis.measure.Distance` object is used,
  157
+it may be expressed in any units (the SQL generated will use units
  158
+converted to those of the field); otherwise, numeric parameters are assumed
  159
+to be in the units of the field.
  160
+
  161
+.. note::
  162
+
  163
+    For PostGIS users, the routine ``ST_distance_sphere`` 
  164
+    is used by default for calculating distances on geographic coordinate systems 
  165
+    -- which may only be called with point geometries [#fndistsphere]_.  Thus, 
  166
+    geographic distance lookups on traditional PostGIS geometry columns are
  167
+    only allowed on :class:`PointField` model fields using a point for the
  168
+    geometry parameter.
  169
+
  170
+.. note::
  171
+
  172
+    PostGIS 1.5 introduced :ref:`geography columns <geography-type>`, which
  173
+    is limited on what geometry types distance queries are performed with.  In
  174
+    other words, if you have ``geography=True`` in your geometry field
  175
+    definition you'll be allowed to peform arbitrary distance queries with your
  176
+    data in geodetic units of WGS84.
  177
+
  178
+
  179
+For example, let's say we have a ``SouthTexasCity`` model (from the 
  180
+`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities 
  181
+in southern Texas::
  182
+
  183
+    from django.contrib.gis.db import models
  184
+    
  185
+    class SouthTexasCity(models.Model):
  186
+        name = models.CharField(max_length=30)
  187
+        # A projected coordinate system (only valid for South Texas!) 
  188
+        # is used, units are in meters.
  189
+        point = models.PointField(srid=32140) 
  190
+        objects = models.GeoManager()
  191
+
  192
+Then distance queries may be performed as follows::
  193
+
  194
+    >>> from django.contrib.gis.geos import *
  195
+    >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
  196
+    >>> from geoapp import SouthTexasCity 
  197
+    # Distances will be calculated from this point, which does not have to be projected.
  198
+    >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
  199
+    # If numeric parameter, units of field (meters in this case) are assumed.
  200
+    >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
  201
+    # Find all Cities within 7 km, > 20 miles away, and > 100 chains  away (an obscure unit)
  202
+    >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
  203
+    >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
  204
+    >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
  205
+
  206
+__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
  207
+
  208
+.. _compatibility-table:
  209
+
  210
+Compatibility Tables
  211
+====================
  212
+
  213
+.. _spatial-lookup-compatibility:
  214
+
  215
+Spatial Lookups
  216
+---------------
  217
+
  218
+The following table provides a summary of what spatial lookups are available
  219
+for each spatial database backend.
  220
+
  221
+=================================  =========  ========  ============ ==========
  222
+Lookup Type                        PostGIS    Oracle    MySQL [#]_   SpatiaLite
  223
+=================================  =========  ========  ============ ==========
  224
+:lookup:`bbcontains`               X                    X            X
  225
+:lookup:`bboverlaps`               X                    X            X
  226
+:lookup:`contained`                X                    X            X
  227
+:lookup:`contains <gis-contains>`  X          X         X            X
  228
+:lookup:`contains_properly`        X
  229
+:lookup:`coveredby`                X          X
  230
+:lookup:`covers`                   X          X
  231
+:lookup:`crosses`                  X                                 X
  232
+:lookup:`disjoint`                 X          X         X            X
  233
+:lookup:`distance_gt`              X          X                      X
  234
+:lookup:`distance_gte`             X          X                      X
  235
+:lookup:`distance_lt`              X          X                      X
  236
+:lookup:`distance_lte`             X          X                      X
  237
+:lookup:`dwithin`                  X          X
  238
+:lookup:`equals`                   X          X         X            X
  239
+:lookup:`exact`                    X          X         X            X
  240
+:lookup:`intersects`               X          X         X            X
  241
+:lookup:`overlaps`                 X          X         X            X
  242
+:lookup:`relate`                   X          X                      X
  243
+:lookup:`same_as`                  X          X         X            X
  244
+:lookup:`touches`                  X          X         X            X
  245
+:lookup:`within`                   X          X         X            X
  246
+:lookup:`left`                     X
  247
+:lookup:`right`                    X
  248
+:lookup:`overlaps_left`            X
  249
+:lookup:`overlaps_right`           X
  250
+:lookup:`overlaps_above`           X
  251
+:lookup:`overlaps_below`           X
  252
+:lookup:`strictly_above`           X
  253
+:lookup:`strictly_below`           X
  254
+=================================  =========  ========  ============ ==========
  255
+
  256
+.. _geoqueryset-method-compatibility:
  257
+
  258
+``GeoQuerySet`` Methods
  259
+-----------------------
  260
+The following table provides a summary of what :class:`GeoQuerySet` methods
  261
+are available on each spatial backend.  Please note that MySQL does not 
  262
+support any of these methods, and is thus excluded from the table.
  263
+
  264
+====================================  =======  ======  ==========
  265
+Method                                PostGIS  Oracle  SpatiaLite
  266
+====================================  =======  ======  ==========
  267
+:meth:`GeoQuerySet.area`              X        X       X
  268
+:meth:`GeoQuerySet.centroid`          X        X       X
  269
+:meth:`GeoQuerySet.collect`           X
  270
+:meth:`GeoQuerySet.difference`        X        X       X
  271
+:meth:`GeoQuerySet.distance`          X        X       X
  272
+:meth:`GeoQuerySet.envelope`          X                X
  273
+:meth:`GeoQuerySet.extent`            X        X
  274
+:meth:`GeoQuerySet.extent3d`          X
  275
+:meth:`GeoQuerySet.force_rhr`         X
  276
+:meth:`GeoQuerySet.geohash`           X
  277
+:meth:`GeoQuerySet.geojson`           X
  278
+:meth:`GeoQuerySet.gml`               X        X
  279
+:meth:`GeoQuerySet.intersection`      X        X       X
  280
+:meth:`GeoQuerySet.kml`               X
  281
+:meth:`GeoQuerySet.length`            X        X       X
  282
+:meth:`GeoQuerySet.make_line`         X
  283
+:meth:`GeoQuerySet.mem_size`          X
  284
+:meth:`GeoQuerySet.num_geom`          X        X       X
  285
+:meth:`GeoQuerySet.num_points`        X        X       X
  286
+:meth:`GeoQuerySet.perimeter`         X        X
  287
+:meth:`GeoQuerySet.point_on_surface`  X        X       X
  288
+:meth:`GeoQuerySet.reverse_geom`      X        X
  289
+:meth:`GeoQuerySet.scale`             X                X
  290
+:meth:`GeoQuerySet.snap_to_grid`      X
  291
+:meth:`GeoQuerySet.svg`               X                X
  292
+:meth:`GeoQuerySet.sym_difference`    X        X       X
  293
+:meth:`GeoQuerySet.transform`         X        X       X
  294
+:meth:`GeoQuerySet.translate`         X                X
  295
+:meth:`GeoQuerySet.union`             X        X       X
  296
+:meth:`GeoQuerySet.unionagg`          X        X       X
  297
+====================================  =======  ======  ==========    
  298
+
  299
+.. rubric:: Footnotes
  300
+.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at  Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
  301
+.. [#fnewkb] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2.
  302
+.. [#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).
  303
+.. [#fndistsphere] *See* PostGIS 1.5 ``ST_distance_sphere`` `documentation <http://postgis.refractions.net/documentation/manual-1.5/ST_Distance_Sphere.html>`_.
  304
+.. [#] 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`.
99  docs/ref/contrib/gis/deployment.txt
... ...
@@ -0,0 +1,99 @@
  1
+===================
  2
+Deploying GeoDjango
  3
+===================
  4
+
  5
+.. warning::
  6
+
  7
+    GeoDjango uses the GDAL geospatial library which is
  8
+    not thread safe at this time.  Thus, it is *highly* recommended
  9
+    to not use threading when deploying -- in other words, use a 
  10
+    an appropriate configuration of Apache or the prefork method
  11
+    when using FastCGI through another web server.
  12
+
  13
+Apache
  14
+======
  15
+In this section there are some example ``VirtualHost`` directives for 
  16
+when deploying using either ``mod_python`` or ``mod_wsgi``.  At this
  17
+time, we recommend ``mod_wsgi``, as it is now officially recommended 
  18
+way to deploy Django applications with Apache.  Moreover, if
  19
+``mod_python`` is used, then a prefork version of Apache must also be
  20
+used.  As long as ``mod_wsgi`` is configured correctly, it does not
  21
+matter whether the version of Apache is prefork or worker.
  22
+
  23
+.. note::
  24
+
  25
+    The ``Alias`` and ``Directory`` configurations in the the examples
  26
+    below use an example path to a system-wide installation folder of Django.  
  27
+    Substitute in an appropriate location, if necessary, as it may be
  28
+    different than the path on your system.
  29
+
  30
+``mod_wsgi``
  31
+------------
  32
+
  33
+Example::
  34
+
  35
+    <VirtualHost *:80>
  36
+      WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1
  37
+      WSGIProcessGroup geodjango
  38
+      WSGIScriptAlias / /home/geo/geodjango/world.wsgi
  39
+  
  40
+      Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
  41
+      <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/">
  42
+        Order allow,deny
  43
+        Options Indexes
  44
+        Allow from all
  45
+        IndexOptions FancyIndexing
  46
+      </Directory>
  47
+    
  48
+    </VirtualHost>
  49
+
  50
+.. warning::
  51
+
  52
+    If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then
  53
+    Apache may crash when running your GeoDjango application.  Increase the 
  54
+    number of ``processes`` instead.
  55
+
  56
+For more information, please consult Django's
  57
+:ref:`mod_wsgi documentation <howto-deployment-modwsgi>`.
  58
+
  59
+``mod_python``
  60
+--------------
  61
+
  62
+Example::
  63
+
  64
+    <VirtualHost *:80>
  65
+    
  66
+      <Location "/">
  67
+        SetHandler mod_python
  68
+        PythonHandler django.core.handlers.modpython
  69
+        SetEnv DJANGO_SETTINGS_MODULE world.settings
  70
+        PythonDebug On
  71
+        PythonPath "['/var/www/apps'] + sys.path"
  72
+      </Location>
  73
+    
  74
+      Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
  75
+      <Location "/media">
  76
+        SetHandler None
  77
+      </Location>
  78
+    
  79
+    </VirtualHost>
  80
+
  81
+.. warning::
  82
+
  83
+   When using ``mod_python`` you *must* be using a prefork version of Apache, or
  84
+   else your GeoDjango application may crash Apache.
  85
+
  86
+For more information, please consult Django's
  87
+:ref:`mod_python documentation <howto-deployment-modpython>`.
  88
+
  89
+Lighttpd
  90
+========
  91
+
  92
+FastCGI
  93
+-------
  94
+
  95
+Nginx
  96
+=====
  97
+
  98
+FastCGI
  99
+-------
97  docs/ref/contrib/gis/feeds.txt
... ...
@@ -0,0 +1,97 @@
  1
+.. _ref-gis-feeds:
  2
+
  3
+================
  4
+Geographic Feeds
  5
+================
  6
+
  7
+.. module:: django.contrib.gis.feeds
  8
+   :synopsis: GeoDjango's framework for generating spatial feeds.
  9
+
  10
+GeoDjango has its own :class:`Feed` subclass that may embed location information
  11
+in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or 
  12
+`W3C Geo`_ standards.  Because GeoDjango's syndication API is a superset of
  13
+Django's, please consult `Django's syndication documentation <ref-contrib-syndication>`
  14
+for details on general usage.
  15
+
  16
+.. _W3C Geo: http://www.w3.org/2003/01/geo/
  17
+
  18
+__ http://georss.org/1.0#simple
  19
+
  20
+Example
  21
+=======
  22
+
  23
+API Reference
  24
+=============
  25
+
  26
+``Feed`` Subclass
  27
+-----------------
  28
+
  29
+.. class:: Feed
  30
+
  31
+   In addition to methods provided by 
  32
+   the :class:`django.contrib.syndication.feeds.Feed`
  33
+   base class, GeoDjango's ``Feed`` class provides
  34
+   the following overrides.  Note that these overrides may be done in multiple ways::
  35
+
  36
+       from django.contrib.gis.feeds import Feed
  37
+
  38
+       class MyFeed(Feed):
  39
+
  40
+            # First, as a class attribute.
  41
+            geometry = ...
  42
+            item_geometry = ...
  43
+
  44
+            # Also a function with no arguments
  45
+            def geometry(self):
  46
+                ...
  47
+
  48
+            def item_geometry(self):
  49
+                ...
  50
+
  51
+            # And as a function with a single argument
  52
+            def geometry(self, obj):
  53
+                ...
  54
+
  55
+            def item_geometry(self, item):
  56
+                ...
  57
+
  58
+   .. method:: geometry(obj)
  59
+
  60
+   Takes the object returned by ``get_object()`` and returns the *feed's*
  61
+   geometry.  Typically this is a ``GEOSGeometry`` instance, or can be a
  62
+   tuple to represent a point or a box.  For example::
  63
+
  64
+       class ZipcodeFeed(Feed):
  65
+
  66
+           def geometry(self, obj):
  67
+               # Can also return: `obj.poly`, and `obj.poly.centroid`.
  68
+               return obj.poly.extent # tuple like: (X0, Y0, X1, Y1).
  69
+
  70
+   .. method:: item_geometry(item)
  71
+
  72
+   Set this to return the geometry for each *item* in the feed.  This
  73
+   can be a ``GEOSGeometry`` instance, or a tuple that represents a
  74
+   point coordinate or bounding box.  For example::
  75
+
  76
+       class ZipcodeFeed(Feed):
  77
+
  78
+           def item_geometry(self, obj):
  79
+	       # Returns the polygon.
  80
+               return obj.poly
  81
+
  82
+``SyndicationFeed`` Subclasses
  83
+------------------------------
  84
+
  85
+The following :class:`django.utils.feedgenerator.SyndicationFeed` subclasses
  86
+are available:
  87
+
  88
+.. class:: GeoRSSFeed
  89
+
  90
+.. class:: GeoAtom1Feed
  91
+
  92
+.. class:: W3CGeoFeed
  93
+
  94
+.. note::
  95
+
  96
+    `W3C Geo`_ formatted feeds only support
  97
+    :class:`~django.contrib.gis.db.models.PointField` geometries.
1,114  docs/ref/contrib/gis/gdal.txt
... ...
@@ -0,0 +1,1114 @@
  1
+.. _ref-gdal:
  2
+
  3
+========
  4
+GDAL API
  5
+========
  6
+
  7
+.. module:: django.contrib.gis.gdal
  8
+   :synopsis: GeoDjango's high-level interface to the GDAL library.
  9
+
  10
+`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary,
  11
+and is a veritable "swiss army knife" of GIS data functionality.  A subset
  12
+of GDAL is the `OGR`__ Simple Features Library, which specializes
  13
+in reading and writing vector geographic data in a variety of standard
  14
+formats.
  15
+
  16
+GeoDjango provides a high-level Python interface for some of the 
  17
+capabilities of OGR, including the reading and coordinate transformation
  18
+of vector spatial data.
  19
+
  20
+.. note::
  21
+
  22
+     Although the module is named ``gdal``, GeoDjango only supports
  23
+     some of the capabilities of OGR.  Thus, none of GDAL's features
  24
+     with respect to raster (image) data are supported at this time.
  25
+   
  26
+__ http://www.gdal.org/
  27
+__ http://www.gdal.org/ogr/
  28
+
  29
+Overview
  30
+========
  31
+
  32
+Sample Data
  33
+-----------
  34
+
  35
+The GDAL/OGR tools described here are designed to help you read in
  36
+your geospatial data, in order for most of them to be useful you have
  37
+to have some data to work with.  If you're starting out and don't yet
  38
+have any data of your own to use, GeoDjango comes with a number of
  39
+simple data sets that you can use for testing.  This snippet will
  40
+determine where these sample files are installed on your computer::
  41
+
  42
+    >>> import os
  43
+    >>> import django.contrib.gis
  44
+    >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__)
  45
+    >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp')
  46
+
  47
+Vector Data Source Objects
  48
+==========================
  49
+
  50
+``DataSource``
  51
+--------------
  52
+
  53
+:class:`DataSource` is a wrapper for the OGR data source object that
  54
+supports reading data from a variety of OGR-supported geospatial file
  55
+formats and data sources using a simple, consistent interface.  Each
  56
+data source is represented by a :class:`DataSource` object which contains
  57
+one or more layers of data.  Each layer, represented by a :class:`Layer`
  58
+object, contains some number of geographic features (:class:`Feature`),
  59
+information about the type of features contained in that layer (e.g.
  60
+points, polygons, etc.), as well as the names and types of any
  61
+additional fields (:class:`Field`) of data that may be associated with
  62
+each feature in that layer.
  63
+
  64
+.. class:: DataSource(ds_input)
  65
+
  66
+   The constructor for ``DataSource`` just a single parameter: the path of
  67
+   the file you want to read.  However, OGR
  68
+   also supports a variety of more complex data sources, including
  69
+   databases, that may be accessed by passing a special name string instead
  70
+   of a path.  For more information, see the `OGR Vector Formats`__
  71
+   documentation.  The :attr:`name` property of a ``DataSource`` 
  72
+   instance gives the OGR name of the underlying data source that it is
  73
+   using.
  74
+
  75
+   Once you've created your ``DataSource``, you can find out how many 
  76
+   layers of data it contains by accessing the :attr:`layer_count` property, 
  77
+   or (equivalently) by using the ``len()`` function.  For information on 
  78
+   accessing the layers of data themselves, see the next section::
  79
+
  80
+       >>> from django.contrib.gis.gdal import DataSource
  81
+       >>> ds = DataSource(CITIES_PATH)
  82
+       >>> ds.name                         # The exact filename may be different on your computer
  83
+       '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp'
  84
+       >>> ds.layer_count                  # This file only contains one layer
  85
+       1
  86
+
  87
+   .. attribute:: layer_count
  88
+
  89
+   Returns the number of layers in the data source.
  90
+
  91
+   .. attribute:: name
  92
+
  93
+   Returns the name of the data source.
  94
+
  95
+__ http://www.gdal.org/ogr/ogr_formats.html
  96
+
  97
+``Layer``
  98
+---------
  99
+
  100
+.. class:: Layer
  101
+
  102
+   ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object.
  103
+   You never create a ``Layer`` object directly.  Instead, you retrieve
  104
+   them from a :class:`DataSource` object, which is essentially a standard
  105
+   Python container of ``Layer`` objects.  For example, you can access a
  106
+   specific layer by its index (e.g. ``ds[0]`` to access the first
  107
+   layer), or you can iterate over all the layers in the container in a
  108
+   ``for`` loop.  The ``Layer`` itself acts as a container for geometric 
  109
+   features.
  110
+
  111
+   Typically, all the features in a given layer have the same geometry type.
  112
+   The :attr:`geom_type` property of a layer is an :class:`OGRGeomType`
  113
+   that identifies the feature type.  We can use it to print out some basic
  114
+   information about each layer in a :class:`DataSource`::
  115
+
  116
+       >>> for layer in ds:
  117
+       ...     print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)
  118
+       ...
  119
+       Layer "cities": 3 Points
  120
+
  121
+   The example output is from the cities data source, loaded above, which
  122
+   evidently contains one layer, called ``"cities"``, which contains three
  123
+   point features.  For simplicity, the examples below assume that you've 
  124
+   stored that layer in the variable ``layer``::
  125
+
  126
+       >>> layer = ds[0]
  127
+
  128
+   .. attribute:: name
  129
+
  130
+   Returns the name of this layer in the data source.
  131
+
  132
+       >>> layer.name
  133
+       'cities'
  134
+
  135
+   .. attribute:: num_feat
  136
+
  137
+   Returns the number of features in the layer.  Same as ``len(layer)``::
  138
+
  139
+       >>> layer.num_feat
  140
+       3
  141
+
  142
+   .. attribute:: geom_type
  143
+
  144
+   Returns the geometry type of the layer, as an :class:`OGRGeomType`
  145
+   object::
  146
+
  147
+       >>> layer.geom_type.name
  148
+       'Point'
  149
+
  150
+   .. attribute:: num_fields
  151
+
  152
+   Returns the number of fields in the layer, i.e the number of fields of
  153
+   data associated with each feature in the layer::
  154
+
  155
+       >>> layer.num_fields
  156
+       4
  157
+
  158
+   .. attribute:: fields
  159
+
  160
+   Returns a list of the names of each of the fields in this layer::
  161
+
  162
+       >>> layer.fields
  163
+       ['Name', 'Population', 'Density', 'Created']
  164
+
  165
+   .. attribute field_types
  166
+
  167
+   Returns a list of the data types of each of the fields in this layer.
  168
+   These are subclasses of ``Field``, discussed below::
  169
+
  170
+       >>> [ft.__name__ for ft in layer.field_types]
  171
+       ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']
  172
+ 
  173
+   .. attribute:: field_widths
  174
+
  175
+   Returns a list of the maximum field widths for each of the fields in
  176
+   this layer::
  177
+
  178
+      >>> layer.field_widths
  179
+      [80, 11, 24, 10]
  180
+
  181
+   .. attribute:: field_precisions
  182
+
  183
+   Returns a list of the numeric precisions for each of the fields in
  184
+   this layer.  This is meaningless (and set to zero) for non-numeric 
  185
+   fields::
  186
+
  187
+       >>> layer.field_precisions
  188
+       [0, 0, 15, 0]
  189
+
  190
+   .. attribute:: extent
  191
+
  192
+   Returns the spatial extent of this layer, as an :class:`Envelope` 
  193
+   object::
  194
+
  195
+      >>> layer.extent.tuple
  196
+      (-104.609252, 29.763374, -95.23506, 38.971823)
  197
+
  198
+   .. attribute:: srs
  199
+
  200
+   Property that returns the :class:`SpatialReference` associated
  201
+   with this layer::
  202
+
  203
+       >>> print layer.srs
  204
+       GEOGCS["GCS_WGS_1984",
  205
+           DATUM["WGS_1984",
  206
+               SPHEROID["WGS_1984",6378137,298.257223563]],
  207
+           PRIMEM["Greenwich",0],
  208
+           UNIT["Degree",0.017453292519943295]]
  209
+
  210
+   If the :class:`Layer` has no spatial reference information associated
  211
+   with it, ``None`` is returned.
  212
+
  213
+   .. attribute:: spatial_filter
  214
+
  215
+   .. versionadded:: 1.2
  216
+
  217
+   Property that may be used to retrieve or set a spatial filter for this
  218
+   layer.  A spatial filter can only be set with an :class:`OGRGeometry`
  219
+   instance, a 4-tuple extent, or ``None``.  When set with something 
  220
+   other than ``None``, only features that intersect the filter will be
  221
+   returned when iterating over the layer::
  222
+
  223
+       >>> print layer.spatial_filter
  224
+       None
  225
+       >>> print len(layer)
  226
+       3
  227
+       >>> [feat.get('Name') for feat in layer]
  228
+       ['Pueblo', 'Lawrence', 'Houston']
  229
+       >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas
  230
+       >>> layer.spatial_filter = ks_extent
  231
+       >>> len(layer)
  232
+       1
  233
+       >>> [feat.get('Name') for feat in layer]
  234
+       ['Lawrence']
  235
+       >>> layer.spatial_filter = None
  236
+       >>> len(layer)
  237
+       3
  238
+
  239
+   .. method:: get_fields()
  240
+
  241
+   A method that returns a list of the values of a given field for each
  242
+   feature in the layer::
  243
+
  244
+      >>> layer.get_fields('Name')
  245
+      ['Pueblo', 'Lawrence', 'Houston']
  246
+
  247
+   .. method:: get_geoms([geos=False])
  248
+
  249
+   A method that returns a list containing the geometry of each feature
  250
+   in the layer.  If the optional argument ``geos`` is set to ``True``
  251
+   then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry`
  252
+   objects. Otherwise, they are returned as :class:`OGRGeometry` objects::
  253
+
  254
+       >>> [pt.tuple for pt in layer.get_geoms()]
  255
+       [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]
  256
+
  257
+   .. method:: test_capability(capability)
  258
+
  259
+   Returns a boolean indicating whether this layer supports the
  260
+   given capability (a string).  Examples of valid capability strings
  261
+   include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``,
  262
+   ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``,
  263
+   ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and 
  264
+   ``'FastSetNextByIndex'``.
  265
+   
  266
+``Feature``
  267
+-----------
  268
+
  269
+.. class:: Feature
  270
+
  271
+
  272
+   ``Feature`` wraps an OGR feature.  You never create a ``Feature``
  273
+   object directly.  Instead, you retrieve them from a :class:`Layer` object.
  274
+   Each feature consists of a geometry and a set of fields containing
  275
+   additional properties.  The geometry of a field is accessible via its
  276
+   ``geom`` property, which returns an :class:`OGRGeometry` object.  A ``Feature``
  277
+   behaves like a standard Python container for its fields, which it returns as
  278
+   :class:`Field` objects: you can access a field directly by its index or name,
  279
+   or you can iterate over a feature's fields, e.g. in a ``for`` loop.
  280
+
  281
+   .. attribute:: geom
  282
+
  283
+   Returns the geometry for this feature, as an ``OGRGeometry`` object::
  284
+
  285
+       >>> city.geom.tuple
  286
+       (-104.609252, 38.255001)
  287
+
  288
+   .. attribute:: get
  289
+
  290
+   A method that returns the value of the given field (specified by name)
  291
+   for this feature, **not** a ``Field`` wrapper object::
  292
+
  293
+       >>> city.get('Population')
  294
+       102121
  295
+
  296
+   .. attribute:: geom_type
  297
+
  298
+   Returns the type of geometry for this feature, as an :class:`OGRGeomType`
  299
+   object.  This will be the same for all features in a given layer, and
  300
+   is equivalent to the :attr:`Layer.geom_type` property of the 
  301
+   :class:`Layer`` object the feature came from.
  302
+
  303
+   .. attribute:: num_fields
  304
+
  305
+   Returns the number of fields of data associated with the feature.
  306
+   This will be the same for all features in a given layer, and is
  307
+   equivalent to the :attr:`Layer.num_fields` property of the 
  308
+   :class:`Layer` object the feature came from.
  309
+
  310
+   .. attribute:: fields
  311
+
  312
+   Returns a list of the names of the fields of data associated with the
  313
+   feature.  This will be the same for all features in a given layer, and
  314
+   is equivalent to the :attr:`Layer.fields` property of the :class:`Layer`
  315
+   object the feature came from.
  316
+
  317
+   .. attribute:: fid
  318
+
  319
+   Returns the feature identifier within the layer::
  320
+
  321
+       >>> city.fid
  322
+       0
  323
+
  324
+   .. attribute:: layer_name
  325
+
  326
+   Returns the name of the :class:`Layer` that the feature came from.
  327
+   This will be the same for all features in a given layer::
  328
+
  329
+       >>> city.layer_name
  330
+       'cities'
  331
+
  332
+   .. attribute:: index
  333
+
  334
+   A method that returns the index of the given field name.  This will be
  335
+   the same for all features in a given layer::
  336
+
  337
+       >>> city.index('Population')
  338
+       1
  339
+
  340
+``Field``
  341
+---------
  342
+
  343
+.. class:: Field
  344
+
  345
+   .. attribute:: name
  346
+
  347
+   Returns the name of this field::
  348
+
  349
+       >>> city['Name'].name
  350
+       'Name'
  351
+
  352
+   .. attribute:: type
  353
+
  354
+   Returns the OGR type of this field, as an integer.  The
  355
+   ``FIELD_CLASSES`` dictionary maps these values onto 
  356
+   subclasses of ``Field``::
  357
+
  358
+       >>> city['Density'].type
  359
+       2
  360
+
  361
+   .. attribute:: type_name
  362
+
  363
+   Returns a string with the name of the data type of this field::
  364
+
  365
+       >>> city['Name'].type_name
  366
+       'String'
  367
+
  368
+   .. attribute:: value
  369
+
  370
+   Returns the value of this field.  The ``Field`` class itself 
  371
+   returns the value as a string, but each subclass returns the 
  372
+   value in the most appropriate form::
  373
+
  374
+       >>> city['Population'].value
  375
+       102121
  376
+
  377
+   .. attribute:: width
  378
+
  379
+   Returns the width of this field::
  380
+
  381
+       >>> city['Name'].width
  382
+       80
  383
+
  384
+   .. attribute:: precision
  385
+
  386
+   Returns the numeric precision of this field.  This is meaningless (and
  387
+   set to zero) for non-numeric fields::
  388
+
  389
+       >>> city['Density'].precision
  390
+       15
  391
+
  392
+   .. method:: as_double()
  393
+
  394
+   Returns the value of the field as a double (float)::
  395
+
  396
+       >>> city['Density'].as_double()
  397
+       874.7
  398
+
  399
+   .. method:: as_int()
  400
+
  401
+   Returns the value of the field as an integer::
  402
+
  403
+       >>> city['Population'].as_int()
  404
+       102121
  405
+
  406
+   .. method:: as_string()
  407
+
  408
+   Returns the value of the field as a string::
  409
+
  410
+       >>> city['Name'].as_string()
  411
+       'Pueblo'
  412
+
  413
+   .. method:: as_datetime()
  414
+
  415
+   Returns the value of the field as a tuple of date and time components::
  416
+
  417
+       >>> city['Created'].as_datetime()
  418
+       (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))
  419
+
  420
+``Driver``
  421
+----------
  422
+
  423
+.. class:: Driver(dr_input)
  424
+
  425
+   The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver.
  426
+
  427
+   .. attribute:: driver_count
  428
+
  429
+   Returns the number of OGR vector drivers currently registered.
  430
+
  431
+
  432
+OGR Geometries
  433
+==============
  434
+
  435
+``OGRGeometry``
  436
+---------------
  437
+
  438
+:class:`OGRGeometry` objects share similar functionality with 
  439
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin
  440
+wrappers around OGR's internal geometry representation.  Thus, 
  441
+they allow for more efficient access to data when using :class:`DataSource`. 
  442
+Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference
  443
+systems and coordinate transformation::
  444
+
  445
+    >>> from django.contrib.gis.gdal import OGRGeometry
  446
+    >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))')
  447
+
  448
+.. class:: OGRGeometry(geom_input[, srs=None])
  <