Idiomatic asynchronous design

Answer 1

You may want to look at Python Twisted. It is a nice Reactor based API that supports asynchronous operations. Proactor is the common term for asynchronous completion handler like frameworks.

Answer 2

Also have a look at the Asynchronous Completion Token and ActiveObject patterns.

Answer 3

This sounds like the Observer design pattern. link.

Your client object is an Observer. Your API belongs to an object that's Observable.

Each client (in Java parlance) implements the Observer interface. In Python, it's a matter of each client offering a number of methods that your observable will use.

class SomeClientInterface( object ):
    def update( self, source, data ):
        # handle data being pushed from Observable source
    def error( self, from, status ):
        # handle error in Observable source

Your Observable object has a way for Observers to register and do other things.

class Observable( object ):
    def __init__( self ):
        self.clients= set()
    def register( self, observer ):
        self.clients.add( observer )
    def whenSomethingHappens( self ):
        # doing work
        if itAllWentToHell:
            for c in self.clients:
                c.error( self, "some status object" )
        else:
            for c in self.clients:
                c.update( self, the pushed data )
    def waitFor( self ):
        # observers are waiting...
        return theData
    def status( self ):
        return self.currentState