GDAL Datasource
===============

The OGR library within GDAL provides access to feature data from a variety of
vector sources including shapefiles and PostGIS.

.. currentmodule:: shelley.datasources.gdal

.. class:: FeatureSource(name, driver=None, layer_name=None, sql=None, extent=None)

    :param name: identifies of the datasource, relative to driver if supplied
    :type name: string
    :param driver: optionally specifices the OGR driver to use
    :type driver: string
    :param layer_name: if needed identifies the layer within the datasource
    :type driver: string
    :param sql: used with a database driver to retrieve the data
    :type sql: string
    :param sql_filter: callable for altering the sql with the supplied bounds if OGR hasn't implemented the spatial filter
    :type add_bounds_sql: callable(sql, bounds) returning sql

Shape files
-----------

    >>> from shelley.datasources.gdal import FeatureSource
    >>> data_source = FeatureSource('world_boundaries/places.shp')
    >>> features = data_source.features()

PostGIS
-------

    >>> data_source = FeatureSource('PG:host=localhost dbname=gis', driver='PostgreSQL', sql='select * from planet_osm_roads')