modifier in python works, but not the same as in the gui I'm trying to use a boolean modifier to difference two objects.  This works, but what it creates is incomplete vs what happens in blender itself.

Here's relevant code:

def difference(self, source_object, modifier_object):
    ## select the object
    bpy.ops.object.select_all(action = 'DESELECT')
    bpy.context.scene.objects.active = source_object

    ## add the boolean modifier to the selected object and apply it.
    bpy.ops.object.modifier_add(type='BOOLEAN')
    bpy.context.object.modifiers["Boolean"].operation = 'DIFFERENCE'
    bpy.context.object.modifiers["Boolean"].object = modifier_object
    bpy.ops.object.modifier_apply(apply_as='DATA', modifier="Boolean")
    modifier_object.hide = True ## hide the second object


If I call this with a cube and a sphere, the sphere is "cut" from the cube as expected, but there's a hole in the cube instead of a complete surface.  What am I doing wrong?  I've looked at a few different answers, for example using object.modifier.new -- but none have worked so far.
Testing your code, it look to works fine with python 2.73, but i was able to reproduce your result with 2.78. 

So, first of all, blender boolean are very bad, sometime they fail for no "good" reason caused by overlapping geometry, edges, holes,... In your case the sphere has a ring exactly aligned with the cube face. 

A general solution would be so move slightly the sphere, let say positionning it in 2.001 would be enough. 

Another solution for Blender 2.78, the boolean now have two solvers, bmesh and Carve. Using carve seems to work better

bpy.context.object.modifiers["Boolean"].solver = 'CARVE'