cobra Package

Warning

The documentation for cobra hasn’t been touched yet! If you want to contribute (or have ideas for better documentation), feel free to send me a pull request or email me.

cobra Package

Cobra RMI Framework

Cobra is a remote method invocation interface that is very “pythony”. It is MUCH like its inspiration pyro, but slimmer and safer for things like threading and object de-registration. Essentially, cobra allows you to call methods from and get/set attributes on objects that exist on a remote system.

class cobra.CobraClientSocket(sockctor, retrymax=None)

Bases: cobra.CobraSocket

cobraTransaction(mtype, objname, data)

This is an API for clients to use. It will retransmit a sendMessage() automagically on recpt of an exception in recvMessage()

reConnect()

Handle the event where we need to reconnect

exception cobra.CobraClosedException

Bases: cobra.CobraException

Raised when a connection is unexpectedly closed.

class cobra.CobraConnectionHandler(daemon, socket)

handleCall(csock, oname, obj, data)

handleClient()

handleError(csock, oname, obj, data)

handleGetAttr(csock, oname, obj, name)

handleGoodbye(csock, oname, obj, data)

handleHello(csock, oname, obj, data)

Hello messages are used to get the initial cache of method names for the newly connected object.

handleSetAttr(csock, oname, obj, data)

class cobra.CobraDaemon(host='', port=5656, sslcrt=None, sslkey=None, sslca=None)

Bases: SocketServer.ThreadingTCPServer

decrefObject(name)

Decref this object and if it reaches 0, unshare it.

fireThread()

getObjectRefCount(name)

getRandomName()

getSharedName(obj)

If this object is shared already, get the name...

getSharedObject(name)

getSharedObjects()

Return a list of (name, obj) for the currently shared objects.

Example:

for name,obj in daemon.getSharedObjects():

print(‘%s: %r’ % (name,obj))

increfObject(name)

shareObject(obj, name=None, doref=False)

Share an object in this cobra server. By specifying doref=True you will let CobraProxy objects decide that the object is done and should be un-shared. Also, if name == None a random name is chosen.

Returns: name (or the newly generated random one)

unshareObject(name)

exception cobra.CobraException

Bases: exceptions.Exception

Base for Cobra exceptions

class cobra.CobraMethod(proxy, methname)

exception cobra.CobraPickleException

Bases: exceptions.Exception

Raised when pickling fails.

class cobra.CobraProxy(URI, retrymax=None, timeout=None, **kwargs)

A proxy object for remote objects shared with Cobra

Additional keyword arguments may depend on protocol.

cobra://

Only the standard args

cobrassl://

sslca - File path to a CA certs file. Causes server validation. sslcrt / sslkey - Client side cert info

class cobra.CobraRequestHandler(request, client_address, server)

Bases: SocketServer.BaseRequestHandler

handle()

exception cobra.CobraRetryException

Bases: exceptions.Exception

Raised when the retrymax (if present) for a proxy object is exceeded.

class cobra.CobraSocket(socket)

getPeerName()

getSockName()

recvExact(size)

recvMessage()

Returns tuple of mtype, objname, and data This method is NOT responsable for re-connection, because there is not context on the server side for what to send on re-connect. Client side uses of the CobraSocket object should use cobraTransaction to ensure re-tranmission of the request on reception errors.

sendExact(buf)

sendMessage(mtype, objname, data)

Send message is responsable for transmission of cobra messages, and socket reconnection in the event that the send fails for network reasons.

class cobra.SocketBuilder(scheme, host, port, timeout, kwargs)

For internal use by CobraClientSocket

cobra.connectSocket(host, port, timeout=None)

Make the long names go away....

cobra.getCallerInfo()

This function may be used from inside a method being called by a remote caller. It will return a tuple of host,port for the other side of the connection... use wisely ;)

cobra.getLocalInfo()

This function returns the local host,port combination being used in the socket servicing the current request

cobra.isCobraUri(uri)

cobra.runCobraServer(host='', port=5656)

cobra.setCallerInfo(callerinfo)

This is necissary because of crazy python method call name munging for thread attributes ;)

cobra.setLocalInfo(localinfo)

cobra.shareObject(obj, name=None, doref=False)

If shareObject is called before startCobraServer or startCobraSslServer, it will call startCobraServer

cobra.startCobraServer(host='', port=5656)

cobra.unshareObject(name)

cluster Module

Cobra’s built in clustering framework

class cobra.cluster.ClusterCallback

Place one of these in the ClusterServer to get synchronous event information about what’s going on in the cluster server. (mostly for the GUI).

workAdded(server, work)

workCanceled(server, work)

workCompletion(server, workid, completion)

workDone(server, work)

workFailed(server, work)

workGotten(server, work)

workStatus(server, workid, status)

workTimeout(server, work)

class cobra.cluster.ClusterClient(name, maxwidth=4, docode=False)

Listen for our name (or any name if name==”*”) on the cobra cluster multicast address and if we find a server in need, go help.

maxwidth is the number of work units to do in parallel docode will enable code sharing with the server

fireRunner(uri)

processWork()

Runs handing out work up to maxwidth until self.go == False.

threadForker(uri)

class cobra.cluster.ClusterQueen(ifip, recast=True)

proxyAnnounceWork(name, cobraname, port)

Send out a multicast announcement to our subjects to go help a cluster server.

class cobra.cluster.ClusterServer(name, maxsize=None, docode=False, bindsrc='', cobrad=None)

addClusterQueen(queenhost)

Inform the ClusterServer about the presence of a ClusterQueen instance on the given host. When the ClusterServer begins to announce work, he will do so in “infrastructure mode” and ask any set queens for help.

addWork(work)

Add a work object to the ClusterServer. This

announceWork()

Announce to our multicast cluster peers that we have work to do! (Or use a queen to proxy to them...)

cancelAllWork(inprog=True)

Cancel all of the currently pending work units. You may specify inprog=False to cancel all queued work units but allow inprogress work units to complete.

cancelWork(workid)

Cancel a work unit by ID.

doneWork(work)

Used by the clients to report work as done.

failWork(work)

This is called for a work unit that is in a failed state. This is most commonly that the work() method has raised an exception.

getWork()

inProgressCount()

How many work units are in progress?

inQueueCount()

How long is the current work unit queue.

openSharedFile(filename)

Return a URI for an open file decriptor for the specified filename.

NOTE: use openSharedFile() method on work unit to get back a proxy.

runServer(firethread=False)

setWorkCompletion(workid, percent)

Set the percentage completion status for this work unit.

setWorkStatus(workid, status)

Set the humon readable status for the given work unit.

shareFileToWorkers(filename)

Add a file to the list of files which are “shared” to worker clients. This allows workers to access a file from the server.

Example:

s.shareFileToWorkers(‘/path/to/file’)

NOTE: Workers may use the openSharedFile() API to access them.

shutdownServer()

timeoutWork(work)

This method may be over-ridden to handle work units that time our for whatever reason.

timerThread()

class cobra.cluster.ClusterWork(timeout=None)

Bases: object

Extend this object to create your own work units. Do it in a proper module (and not __main__ to be able to use this in conjunction with cobra.dcode).

done()

This is called back on the server once a work unit is complete and returned.

isTimedOut()

Check if this work unit is timed out.

openSharedFile(filename)

A helper API to open a file like object on the server.

Example:

fd = self.openSharedFile(‘/foo/bar/baz’) fbytes = fd.read()

NOTE: The server must use shareFileToWorkers().

setCompletion(percent)

Work units may call this whenever they like to tell the server how far along their work they are.

setStatus(status)

Work units may call this to inform the server of their status.

touch()

Update the internal “touch time” which is used by the timeout subsystem to see if this work unit has gone too long without making progress...

work()

Actually do the work associated with this work object.

exception cobra.cluster.InvalidInProgWorkId(workid)

Bases: exceptions.Exception

class cobra.cluster.VerboseCallback

Bases: cobra.cluster.ClusterCallback

workAdded(server, work)

workCanceled(server, work)

workCompletion(server, workid, completion)

workDone(server, work)

workFailed(server, work)

workGotten(server, work)

workStatus(server, workid, status)

workTimeout(server, work)

cobra.cluster.getAndDoWork(uri, docode=False)

cobra.cluster.getHostPortFromUri(uri)

Take the server URI and pull out the host and port for use in building the dcode uri.

cobra.cluster.runAndWaitWork(server, work)

cobra.cluster.workThread(server, work)

dcode Module

Cobra’s distributed code module capable of allowing serialization of code from one system to another.

Particularly useful for clustering and workunit stuff.

class cobra.dcode.DcodeFinder

Bases: object

This is the module finder which is exposed by a dcode server to allow clients to attempt to find modules.

find_module(fullname, uri, path=None)

class cobra.dcode.DcodeImporter(uri, retrymax=3, timeout=10)

Bases: object

This object goes into the client side import path_hooks to allow cobra:// uri’s to be added to the import path.

find_module(fullname, path=None)

class cobra.dcode.DcodeLoader(fbytes, filename, path)

Bases: object

This object gets pickled by the DcodeFinder and returned to the client who calls load_module.

get_source(name)

load_module(fullname)

cobra.dcode.addDcodeServer(server, port=None, override=False, ssl=False)

cobra.dcode.enableDcodeClient()

Once having called this, a client will be able to add cobra URIs to sys.path (one will be added automatically for the optional server parameter) and code will be imported via the distributed method.

cobra.dcode.enableDcodeServer()

Submodules

• tools Package
  • cluster_queen Module
  • cluster_worker Module