==============
OGR Inspection
==============

.. module:: django.contrib.gis.utils.ogrinspect
    :synopsis: Utilities for inspecting OGR data sources.
    :noindex:

.. currentmodule:: django.contrib.gis.utils

ogrinspect
==========

.. function:: ogrinspect(data_source, model_name, **kwargs)

Given a data source (either a string or a
:class:`~django.contrib.gis.gdal.DataSource` object) and a string model
name this function will generate a GeoDjango model.

Usage:

    >>> from django.contrib.gis.utils import ogrinspect
    >>> ogrinspect('/path/to/shapefile.shp', 'NewModel')

...will print model definition to stdout.

Or put the following code in a python script::

    # generate_model.py
    from django.contrib.gis.utils import ogrinspect
    shp_file = 'data/mapping_hacks/world_borders.shp'
    model_name = 'WorldBorders'

    print(ogrinspect(shp_file, model_name, multi_geom=True, srid=4326, geom_name='shapes', blank=True))

...and run the following command to generate the ``myapp/models.py``
file::

    $ python generate_model.py > myapp/models.py

Required Arguments
    ``datasource``: string or DataSource object to file pointer

    ``model name``: name of new model class to create

Optional Keyword Arguments
    ``geom_name``: For specifying the model name for the Geometry Field. Otherwise
    will default to ``geom``.

    ``layer_key``: The key for specifying which layer in the DataSource to use;
    defaults to 0 (the first layer).  May be an integer index or a string
    identifier for the layer.

    ``srid``: The SRID to use for the Geometry Field.  If it can be determined,
    the SRID of the datasource is used.

    ``multi_geom``: Boolean (default: False) - specify as multigeometry.

    ``name_field``: String - specifies a field name to return for the
    ``__unicode__`` / ``__str__`` function (which will be generated if
    specified).

    ``imports``: Boolean (default: True) - set to False to omit the
    `from django.contrib.gis.db import models` code from the
    autogenerated models thus avoiding duplicated imports when building
    more than one model by batching ogrinspect()

    ``decimal``: Boolean or sequence (default: False).  When set to True
    all generated model fields corresponding to the ``OFTReal`` type will
    be ``DecimalField`` instead of ``FloatField``. A sequence of specific
    field names to generate as ``DecimalField`` may also be used.

    ``blank``: Boolean or sequence (default: False). When set to True all
    generated model fields will have ``blank=True``. If the user wants to
    give specific fields to have blank, then a list/tuple of OGR field
    names may be used.

    ``null``: Boolean (default: False) - When set to True all generated
    model fields will have ``null=True``. If the user wants to specify
    give specific fields to have null, then a list/tuple of OGR field
    names may be used.

mapping
=======

.. function:: mapping(data_source, geom_name='geom', layer_key=0, multi_geom=False)

Given a :class:`~django.contrib.gis.gdal.DataSource`, generates a dictionary
that may be used for invoking the
:class:`~django.contrib.gis.utils.LayerMapping` utility.

Keyword Arguments:
    ``geom_name``: The name of the geometry field to use for the model.

    ``layer_key``: The key for specifying which layer in the
    :class:`~django.contrib.gis.gdal.DataSource` to use; defaults to 0 (the
    first layer).  May be an integer index or a string identifier for the
    layer.

    ``multi_geom``: Boolean (default: False) - specify as multigeometry.