gis: Added the encoding keyword for string fields in OGR data sources; improved docstrings.

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@6422 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/contrib/gis/utils/layermapping.py

@@ -18,12 +18,15 @@ Requirements:  OGR C Library (from GDAL) required.
 Usage: 
   lm = LayerMapping(model, source_file, mapping) where,
 
-  model -- GeoDjango model (not an instance)
+  model:
+   GeoDjango model (not an instance)
 
-  data -- OGR-supported data source file (e.g. a shapefile) or
+  data:
+   OGR-supported data source file (e.g. a shapefile) or
     gdal.DataSource instance
 
-  mapping -- A python dictionary, keys are strings corresponding
+  mapping:
+   A python dictionary, keys are strings corresponding
    to the GeoDjango model field, and values correspond to
    string field names for the OGR feature, or if the model field
    is a geographic then it should correspond to the OGR
@@ -34,10 +37,14 @@ Keyword Args:
    The index of the layer to use from the Data Source (defaults to 0)
 
   source_srs:
-    Use this to specify the source SRS manually (for example, some 
+   Use this to specify the source SRS manually (for example, 
-     shapefiles don't come with a '.prj' file).  A SRID integer, a
+   some shapefiles don't come with a '.prj' file).  An integer SRID,
-     WKT string, a SpatialReference, and a SpatialRefSys object are
+   a string WKT, and SpatialReference objects are valid parameters.
-     all valid parameters here.
+
+  encoding:
+   Specifies the encoding of the string in the OGR data source.
+   For example, 'latin-1', 'utf-8', and 'cp437' are all valid
+   encoding parameters.
 
 Example:
 
@@ -234,7 +241,7 @@ def check_srs(layer, source_srs):
 class LayerMapping:
     "A class that maps OGR Layers to Django Models."
 
-    def __init__(self, model, data, mapping, layer=0, source_srs=None):
+    def __init__(self, model, data, mapping, layer=0, source_srs=None, encoding=None):
         "Takes the Django model, the data source, and the mapping (dictionary)"
 
         # Getting the field names and types from the model
@@ -256,6 +263,17 @@ class LayerMapping:
         self.model = model
         self.source_srs = check_srs(self.layer, source_srs)
 
+        # Setting the encoding for OFTString fields, if specified.
+        if encoding:
+            # Making sure the encoding exists, if not a LookupError
+            #  exception will be thrown.
+            from codecs import lookup
+            lookup(encoding)
+            self.encoding = encoding
+        else:
+            self.encoding = None
+
+    # Either the import will work, or it won't be committed.
     @transaction.commit_on_success
     def save(self, verbose=False):
         "Runs the layer mapping on the given SHP file, and saves to the database."
@@ -310,8 +328,14 @@ class LayerMapping:
                     val = g.wkt
                 else:
                     ## Otherwise, this is an OGR field type
-                    fi = feat.index(ogr_field)
+                    fld = feat[ogr_field]
-                    val = feat[fi].value
+
+                    if isinstance(fld, OFTString) and self.encoding:
+                        # The encoding for OGR data sources may be specified here
+                        #  (e.g., 'cp437' for Census Bureau boundary files).
+                        val = unicode(fld.value, self.encoding)
+                    else:
+                        val = fld.value
 
                 if is_fk:
                     rel_obj = None
@@ -343,4 +367,3 @@ class LayerMapping:
                     raise
                 except Exception, e:
                     print "Failed to save %s\n  Continuing" % kwargs
-