python/lib/django_1_4/django/contrib/gis/utils/ogrinspect.py

   1 """
   2 This module is for inspecting OGR data sources and generating either
   3 models for GeoDjango and/or mapping dictionaries for use with the
   4 `LayerMapping` utility.
   5
   6 Author: Travis Pinney, Dane Springmeyer, & Justin Bronn
   7 """
   8 from itertools import izip
   9 # Requires GDAL to use.
  10 from django.contrib.gis.gdal import DataSource
  11 from django.contrib.gis.gdal.field import OFTDate, OFTDateTime, OFTInteger, OFTReal, OFTString, OFTTime
  12
  13 def mapping(data_source, geom_name='geom', layer_key=0, multi_geom=False):
  14     """
  15     Given a DataSource, generates a dictionary that may be used
  16     for invoking the LayerMapping utility.
  17
  18     Keyword Arguments:
  19      `geom_name` => The name of the geometry field to use for the model.
  20
  21      `layer_key` => The key for specifying which layer in the DataSource to use;
  22        defaults to 0 (the first layer).  May be an integer index or a string
  23        identifier for the layer.
  24
  25      `multi_geom` => Boolean (default: False) - specify as multigeometry.
  26     """
  27     if isinstance(data_source, basestring):
  28         # Instantiating the DataSource from the string.
  29         data_source = DataSource(data_source)
  30     elif isinstance(data_source, DataSource):
  31         pass
  32     else:
  33         raise TypeError('Data source parameter must be a string or a DataSource object.')
  34
  35     # Creating the dictionary.
  36     _mapping = {}
  37
  38     # Generating the field name for each field in the layer.
  39     for field in data_source[layer_key].fields:
  40         mfield = field.lower()
  41         if mfield[-1:] == '_': mfield += 'field'
  42         _mapping[mfield] = field
  43     gtype = data_source[layer_key].geom_type
  44     if multi_geom and gtype.num in (1, 2, 3): prefix = 'MULTI'
  45     else: prefix = ''
  46     _mapping[geom_name] = prefix + str(gtype).upper()
  47     return _mapping
  48
  49 def ogrinspect(*args, **kwargs):
  50     """
  51     Given a data source (either a string or a DataSource object) and a string
  52     model name this function will generate a GeoDjango model.
  53
  54     Usage:
  55
  56     >>> from django.contrib.gis.utils import ogrinspect
  57     >>> ogrinspect('/path/to/shapefile.shp','NewModel')
  58
  59     ...will print model definition to stout
  60
  61     or put this in a python script and use to redirect the output to a new
  62     model like:
  63
  64     $ python generate_model.py > myapp/models.py
  65
  66     # generate_model.py
  67     from django.contrib.gis.utils import ogrinspect
  68     shp_file = 'data/mapping_hacks/world_borders.shp'
  69     model_name = 'WorldBorders'
  70
  71     print ogrinspect(shp_file, model_name, multi_geom=True, srid=4326,
  72                      geom_name='shapes', blank=True)
  73
  74     Required Arguments
  75      `datasource` => string or DataSource object to file pointer
  76
  77      `model name` => string of name of new model class to create
  78
  79     Optional Keyword Arguments
  80      `geom_name` => For specifying the model name for the Geometry Field.
  81        Otherwise will default to `geom`
  82
  83      `layer_key` => The key for specifying which layer in the DataSource to use;
  84        defaults to 0 (the first layer).  May be an integer index or a string
  85        identifier for the layer.
  86
  87      `srid` => The SRID to use for the Geometry Field.  If it can be determined,
  88        the SRID of the datasource is used.
  89
  90      `multi_geom` => Boolean (default: False) - specify as multigeometry.
  91
  92      `name_field` => String - specifies a field name to return for the
  93        `__unicode__` function (which will be generated if specified).
  94
  95      `imports` => Boolean (default: True) - set to False to omit the
  96        `from django.contrib.gis.db import models` code from the
  97        autogenerated models thus avoiding duplicated imports when building
  98        more than one model by batching ogrinspect()
  99
 100      `decimal` => Boolean or sequence (default: False).  When set to True
 101        all generated model fields corresponding to the `OFTReal` type will
 102        be `DecimalField` instead of `FloatField`.  A sequence of specific
 103        field names to generate as `DecimalField` may also be used.
 104
 105      `blank` => Boolean or sequence (default: False).  When set to True all
 106        generated model fields will have `blank=True`.  If the user wants to
 107        give specific fields to have blank, then a list/tuple of OGR field
 108        names may be used.
 109
 110      `null` => Boolean (default: False) - When set to True all generated
 111        model fields will have `null=True`.  If the user wants to specify
 112        give specific fields to have null, then a list/tuple of OGR field
 113        names may be used.
 114
 115     Note: This routine calls the _ogrinspect() helper to do the heavy lifting.
 116     """
 117     return '\n'.join(s for s in _ogrinspect(*args, **kwargs))
 118
 119 def _ogrinspect(data_source, model_name, geom_name='geom', layer_key=0, srid=None,
 120                 multi_geom=False, name_field=None, imports=True,
 121                 decimal=False, blank=False, null=False):
 122     """
 123     Helper routine for `ogrinspect` that generates GeoDjango models corresponding
 124     to the given data source.  See the `ogrinspect` docstring for more details.
 125     """
 126     # Getting the DataSource
 127     if isinstance(data_source, str):
 128         data_source = DataSource(data_source)
 129     elif isinstance(data_source, DataSource):
 130         pass
 131     else:
 132         raise TypeError('Data source parameter must be a string or a DataSource object.')
 133
 134     # Getting the layer corresponding to the layer key and getting
 135     # a string listing of all OGR fields in the Layer.
 136     layer = data_source[layer_key]
 137     ogr_fields = layer.fields
 138
 139     # Creating lists from the `null`, `blank`, and `decimal`
 140     # keyword arguments.
 141     def process_kwarg(kwarg):
 142         if isinstance(kwarg, (list, tuple)):
 143             return [s.lower() for s in kwarg]
 144         elif kwarg:
 145             return [s.lower() for s in ogr_fields]
 146         else:
 147             return []
 148     null_fields = process_kwarg(null)
 149     blank_fields = process_kwarg(blank)
 150     decimal_fields = process_kwarg(decimal)
 151
 152     # Gets the `null` and `blank` keywords for the given field name.
 153     def get_kwargs_str(field_name):
 154         kwlist = []
 155         if field_name.lower() in null_fields: kwlist.append('null=True')
 156         if field_name.lower() in blank_fields: kwlist.append('blank=True')
 157         if kwlist: return ', ' + ', '.join(kwlist)
 158         else: return ''
 159
 160     # For those wishing to disable the imports.
 161     if imports:
 162         yield '# This is an auto-generated Django model module created by ogrinspect.'
 163         yield 'from django.contrib.gis.db import models'
 164         yield ''
 165
 166     yield 'class %s(models.Model):' % model_name
 167
 168     for field_name, width, precision, field_type in izip(ogr_fields, layer.field_widths, layer.field_precisions, layer.field_types):
 169         # The model field name.
 170         mfield = field_name.lower()
 171         if mfield[-1:] == '_': mfield += 'field'
 172
 173         # Getting the keyword args string.
 174         kwargs_str = get_kwargs_str(field_name)
 175
 176         if field_type is OFTReal:
 177             # By default OFTReals are mapped to `FloatField`, however, they
 178             # may also be mapped to `DecimalField` if specified in the
 179             # `decimal` keyword.
 180             if field_name.lower() in decimal_fields:
 181                 yield '    %s = models.DecimalField(max_digits=%d, decimal_places=%d%s)' % (mfield, width, precision, kwargs_str)
 182             else:
 183                 yield '    %s = models.FloatField(%s)' % (mfield, kwargs_str[2:])
 184         elif field_type is OFTInteger:
 185             yield '    %s = models.IntegerField(%s)' % (mfield, kwargs_str[2:])
 186         elif field_type is OFTString:
 187             yield '    %s = models.CharField(max_length=%s%s)' % (mfield, width, kwargs_str)
 188         elif field_type is OFTDate:
 189             yield '    %s = models.DateField(%s)' % (mfield, kwargs_str[2:])
 190         elif field_type is OFTDateTime:
 191             yield '    %s = models.DateTimeField(%s)' % (mfield, kwargs_str[2:])
 192         elif field_type is OFTTime:
 193             yield '    %s = models.TimeField(%s)' % (mfield, kwargs_str[2:])
 194         else:
 195             raise TypeError('Unknown field type %s in %s' % (field_type, mfield))
 196
 197     # TODO: Autodetection of multigeometry types (see #7218).
 198     gtype = layer.geom_type
 199     if multi_geom and gtype.num in (1, 2, 3):
 200         geom_field = 'Multi%s' % gtype.django
 201     else:
 202         geom_field = gtype.django
 203
 204     # Setting up the SRID keyword string.
 205     if srid is None:
 206         if layer.srs is None:
 207             srid_str = 'srid=-1'
 208         else:
 209             srid = layer.srs.srid
 210             if srid is None:
 211                 srid_str = 'srid=-1'
 212             elif srid == 4326:
 213                 # WGS84 is already the default.
 214                 srid_str = ''
 215             else:
 216                 srid_str = 'srid=%s' % srid
 217     else:
 218         srid_str = 'srid=%s' % srid
 219
 220     yield '    %s = models.%s(%s)' % (geom_name, geom_field, srid_str)
 221     yield '    objects = models.GeoManager()'
 222
 223     if name_field:
 224         yield ''
 225         yield '    def __unicode__(self): return self.%s' % name_field