Gotchas in the GDAL and OGR Python Bindings

before

>>> from osgeo import gdal
>>> gdal.Open('C:\\foo.img')
ERROR 4: `C:\foo.img' does not exist in the file system,
and is not recognised as a supported dataset name.

>>>

>>> from osgeo import gdal
>>> gdal.UseExceptions()        # Enable exceptions
>>> gdal.Open('C:\\foo.img')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: `C:\foo.img' does not exist in the file system,
and is not recognised as a supported dataset name.

>>>

>>> from osgeo import gdal
>>> dataset = gdal.Open('C:\\RandomData.img')
>>> band = dataset.GetRasterBand(1)
>>> print band.Checksum()
31212

>>> from osgeo import gdal
>>> dataset = gdal.Open('C:\\RandomData.img')
>>> band = dataset.GetRasterBand(1)
>>> del dataset           # This will cause the Python garbage collector to deallocate dataset
>>> band.GetChecksum()    # This will now crash Python because the band's dataset is gone
< Python crashes >

>>> from osgeo import gdal
>>> print gdal.Open('C:\\RandomData.img').GetRasterBand(1).Checksum()
< Python crashes >

>>> feat = lyr.GetNextFeature()
>>> geom = feat.GetGeometryRef()     # geom contains a reference into the C++ geometry object maintained by the C++ feature object
>>> del feat                         # This deallocates the C++ feature object, and its C++ geometry
>>> print(geom.ExportToWkt())        # Crash here. The C++ geometry no longer exists
< Python crashes >

>>> point = ogr.Geometry(ogr.wkbPoint)
>>> feature = ogr.Feature(layer_defn)
>>> feature.SetGeometryDirectly(point)    # Transfers ownership of the C++ geometry from point to feature
>>> del feature                           # point becomes implicitly invalid, because feature owns the C++ geometry
>>> print point.ExportToWkt()             # Crash here
< Python crashes >

>>> feature = lyr.GetNextFeature()
>>> field_defn = ogr.FieldDefn("foo", ogr.OFTString)
>>> lyr.CreateField(field_defn)                       # now, existing features deriving from this layer are invalid
>>> feature.DumpReadable()                            # segfault
< Python crashes >

>>> lyr = inDataSource.GetLayer()
>>> lyr.SetAttributeFilter("PIN = '0000200001'")      # this is a unique filter for only one record
>>> for i in range( 0, lyr.GetFeatureCount() ):
...    feat = lyr.GetFeature( i )
...    print feat                                     # this will print one feat, but it's the first feat in the Layer and not the filtered feat  
...

> I have some Python code that uses OGR geometry objects internally, creating
> them like this:
> 
> point = ogr.Geometry(ogr.wkbPoint)
> 
> Does this code need to explicitly destroy these geometries, like the
> following, to avoid leaks, or can it simply allow them to go out of scope
> and have Python's reference counting and garbage collector clean them up?
> 
> point.Destroy()

There's no reason to call Destroy(), at all. Native object gets destroyed when 
Python object goes out of scope, or when they are assigned to None. So replace 
foo.Destroy() by foo = None if you really want to control when the underlying 
C++ object is destroyed.

> I'm sorry for my ignorance here. I found a nice GDAL tutorial that seems to
> say they *should* be explicitly destroyed in certain circumstances (see
> http://www.gis.usu.edu/~chrisg/python/2009/lectures/ospy_slides2.pdf, page
> 12). But I have not really seen any other examples of this.
> 

Destroy() was perhaps necessary with old-gen bindings, but I'm not even sure 
of that... Perhaps this shouldn't have been exposed at all... But, as 
mentionned in the slides, it is true that there are situations where you 
shouldn't call Destroy() at all.

>>> from osgeo import gdal
>>> driver = gdal.GetDriverByName('GTiff')
>>> dst_ds = driver.Create('new.tif', 10, 15)
>>> band = dst_ds.GetRasterBand(1)
>>> arr = band.ReadAsArray()  # raster values are all zero
>>> arr[2, 4:] = 50  # modify some data
>>> band.WriteArray(arr)  # raster file still unmodified
>>> band = None  # dereference band to avoid gotcha described previously
>>> dst_ds = None  # save, close

def error_handler(err_level, err_no, err_msg):

    if err_class >= gdal.CE_Warning:
        raise RuntimeError(err_level, err_no, err_msg) #this exception does not propagate back to main thread!

if __name__=='__main__':

    #Test custom error handler
    gdal.PushErrorHandler(error_handler)
    gdal.Error(gdal.CE_Warning,2,'test warning message')
    gdal.PopErrorHandler()

class GdalErrorHandler(object):
    def __init__(self):
        self.err_level=gdal.CE_None
        self.err_no=0
        self.err_msg=''

    def handler(self, err_level, err_no, err_msg):
        self.err_level=err_level
        self.err_no=err_no
        self.err_msg=err_msg

if __name__=='__main__':

    err=GdalErrorHandler()
    handler=err.handler # Note don't pass class method directly or python segfaults
                        # due to a reference counting bug 
                        # http://trac.osgeo.org/gdal/ticket/5186#comment:4

    gdal.PushErrorHandler(handler)
    gdal.UseExceptions() #Exceptions will get raised on anything >= gdal.CE_Failure

    try:
        gdal.Error(gdal.CE_Warning,1,'Test warning message')
    except Exception as e:
        print 'Operation raised an exception'
        raise
    else:
        if err.err_level >= gdal.CE_Warning:
            print 'Operation raised an warning'
            raise RuntimeError(err.err_level, err.err_no, err.err_msg)
    finally:
        gdal.PopErrorHandler()

>>> from osgeo import ogr
>>> ogr.UseExceptions()
>>> ogr.CreateGeometryFromWkt('POINT(1 2)')          # Create a point using valid WKT
<osgeo.ogr.Geometry; proxy of <Swig Object of type 'OGRGeometryShadow *' at 0x244b658> >
>>> ogr.CreateGeometryFromWkt('blah blah blah')      # Now try to create one using invalid WKT
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python25\lib\site-packages\osgeo\ogr.py", line 2885, in CreateGeometryFromWkt
    return _ogr.CreateGeometryFromWkt(*args, **kwargs)
RuntimeError: OGR Error: Unsupported geometry type
>>> ogr.CreateGeometryFromWkt('POINT(1 2)')          # Now try to to create one using valid WKT again
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python25\lib\site-packages\osgeo\ogr.py", line 2885, in CreateGeometryFromWkt
    return _ogr.CreateGeometryFromWkt(*args, **kwargs)
RuntimeError: OGR Error: Unsupported geometry type

>>> ogr.CreateGeometryFromWkt('blah blah blah')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python25\lib\site-packages\osgeo\ogr.py", line 2885, in CreateGeometryFromWkt
    return _ogr.CreateGeometryFromWkt(*args, **kwargs)
RuntimeError: OGR Error: Unsupported geometry type
>>> from osgeo import gdal
>>> gdal.ErrorReset()
>>> ogr.CreateGeometryFromWkt('POINT(1 2)')
<osgeo.ogr.Geometry; proxy of <Swig Object of type 'OGRGeometryShadow *' at 0x244b7a8> >

Context Navigation

Gotchas in the GDAL and OGR Python Bindings

Gotchas that are by design... or per history

Python bindings do not raise exceptions unless you explicitly call `UseExceptions()`

Python crashes if you use an object after deleting an object it has a relationship with

Python crashes if you add a new field to an OGR layer when features deriving from this layer definition are still active

Layers with attribute filters (`SetAttributeFilter()`) will only return filtered features when using `GetNextFeature()`

Certain objects contain a `Destroy()` method, but you should never use it

Saving and closing datasets/datasources

Exceptions raised in custom error handlers do not get caught

Gotchas fixed in GDAL 1.8.0

`gdal.ErrorReset()` must be called after an error occurs, or it will keep happening

Gotchas that result from bugs or behaviors of other software

Python crashes in GDAL functions when you upgrade or downgrade numpy

Python bindings cannot be used successfully from ArcGIS in-process geoprocessing tools (ArcGIS 9.3 and later)

Download in other formats:

Context Navigation

Gotchas in the GDAL and OGR Python Bindings

Gotchas that are by design... or per history

Python bindings do not raise exceptions unless you explicitly call UseExceptions()

Python crashes if you use an object after deleting an object it has a relationship with

Python crashes if you add a new field to an OGR layer when features deriving from this layer definition are still active

Layers with attribute filters (SetAttributeFilter()) will only return filtered features when using GetNextFeature()

Certain objects contain a Destroy() method, but you should never use it

Saving and closing datasets/datasources

Exceptions raised in custom error handlers do not get caught

Gotchas fixed in GDAL 1.8.0

gdal.ErrorReset() must be called after an error occurs, or it will keep happening

Gotchas that result from bugs or behaviors of other software

Python crashes in GDAL functions when you upgrade or downgrade numpy

Python bindings cannot be used successfully from ArcGIS in-process geoprocessing tools (ArcGIS 9.3 and later)

Download in other formats:

Python bindings do not raise exceptions unless you explicitly call `UseExceptions()`

Layers with attribute filters (`SetAttributeFilter()`) will only return filtered features when using `GetNextFeature()`

Certain objects contain a `Destroy()` method, but you should never use it

`gdal.ErrorReset()` must be called after an error occurs, or it will keep happening