
DOPY - Distributed Objects for Python
=====================================

DOPY is a small distributed object system written entirely in Python.  It is
not intended to be CORBA compliant.  Instead, it aims to be extremely easy
to use and to support Python's dynamic nature - methods are invoked
dynamically, parameters are passed by copy.  Any python object that can be
pickled can automatically be passed as a parameter or a return value, and
any Python object can be published as a distributed object.

The current version of DOPY is an extremely immature alpha release.  Its
only supported protocol is `TCP/IP`, and you must have thread support to be
able to use it (there is a facility for non-threaded use, but it is entirely
untested). I've distributed it because others might find it useful (even in
its current state) and because I'm interested in the feedback of the Python
development community.

This is just a brief "README" file, see also the evolving 
\ref(Manual.html User Manual) for more in-depth information.

Installation
------------

Unzip the distribution zip file into somewhere on your PYTHONPATH
(preferably in site-packages under your main python tree) and rename the
"dopy-<version number>" directory to "dopy".  From within that directory,
just run "dopyserver" (if your system understands `#!`, "python -i
dopyserver" if not) to start the server, then run "dopyclient <serverhost>"
in another session (you may omit the host parameter if connecting to the
local host). If everything is working right, you should see the following
output from the client:

{{
   connecting to localhost:9600...
   test of basic method invocation ok
   test of keyword parms ok
   test of exceptions ok
}}

Unfortunately, distutils does not currently provide for the installation
of documentation files.  However, documentation should work right from the
distribution tree.  Just point your browser right at README.html (as you may be
doing right now :-) or Manual.html.  You may want to copy the entire
distribution tree to wherever you like to store your documentation files.

5-Minute Tutorial
-----------------

DOPY is intended to be really easy to use.  To create a server object, all
you need to do is create a server instance, get the hub, and register the
object.

To create a TCP server, import the dopy.tcp module and create the server
as follows:

{{
   import dopy.tcp
   dopy.tcp.makeServer(9600)
}}

This creates a `TCP/IP` server listening on port 9600.

The Hub is a singleton object that manages connections and provides a basic
set of services (much like a CORBA orb).  Get the hub with the getHub()
function:

{{
   hub = dopy.getHub()
}}

To publish an object, you must call the hub's addObject() method with a name
and the object.  The name is the key that must be used when obtaining a
proxy for the object on the client side:

{{
   hub.addObject('myObject', anObject)
}}

At this point you can use the hub.mainloop() to just sit there and process
messages.  In the threaded model, mainloop reads raw input and evaluates it
so that you may execute one-line python commands while it is servicing
requests in the background threads.

On the client side, you need only use the dopy.tcp.remote() function to use
the remote object:

{{
   import dopy.tcp
   obj = dopy.tcp.remote('localhost', 9600, 'myObject')
}}

The parameters of this function are host name, port number, and object name
(the name used in the addObject() call on the server side).  Now you can
call any methods provided by the remote object just as you ordinarily would.

Limitations
-----------

DOPY is not CORBA compliant.  To get all of the advantages of CORBA, use
Fnorb or ILU.

You do not have access to the non-method attributes of the remote object:
your only interface to the remote object is through method invocation.

At this time, DOPY requires threads.  There is non-threaded "select" based
code, but this is completely untested at this time.

Why Use a Non-CORBA Distributed Object System?
----------------------------------------------

As stated earlier, DOPY is not CORBA-compliant.  It is not suitable for use
between anything other than Python programs.  However, because it is
Python-specific, it has certain advantages over CORBA:

-  You don't have to worry about maintaining and distributing stub files,
   method resolution and invocation is performed on the server side.
-  Arbitrarily complex Python objects can be passed as parameters, return
   values, and exceptions.
-  New protocols can easily be added to the system (CORBA facilitates
   multiple protocols, but in my perusal of the Fnorb source code, adding a
   new protocol appeared to be a non-trivial exercise; in DOPY, it's much
   easier).

Code Contribution Policy
------------------------

I'll gladly accept fixes, enhancements, and add-ons providing that the
contributor agrees that the changes may be distributed under the terms of
the current license.

Copyright Info
--------------

Copyright (C) 1999,2001,2002 Michael A. Muller

Permission is granted to use, modify and redistribute this document,
providing that the following conditions are met:

-  This `copyright/licensing` notice must remain intact.
-  If the code is modified and redistributed, the modifications must 
   include documentation indicating that the code has been modified.
-  The author(s) of this code must be indemnified and held harmless
   against any damage resulting from the use of this code.

This code comes with ABSOLUTELY NO WARRANTEE, not even the implied 
warrantee of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
