PyORBit
=======

This is a Python language binding for the ORBit2 CORBA implementation.
It aims to take advantage of new features found in ORBit2 to make
language bindings more efficient.  This includes:
  - Use of ORBit2 type libraries to generate stubs
  - use of the ORBit_small_invoke_stub() call for operation
    invocation, which allows for short circuited invocation on local
    objects.

Where it makes sense, this binding tries to stay compatible with the
Python language mapping, which can be found on the OMG web site:
    http://www.omg.org/cgi-bin/doc?formal/02-09-07

Currently only the client side of the binding has been done.


Required ORBit2 Version
-----------------------

Due to a number of bugs in ORBit2 2.4.3, PyORBit requires version
2.4.4 or later.  Versions of ORBit2 taken from the HEAD branch can
also be used.

As some of the bugs were in the IDL compiler, you may need to
recompile code generated by the IDL compiler.  This includes the
"Bonobo" typelib (distributed with libbonobo), and probably other
libraries.


Typelibs
--------

Before using an interface, you should build a typelib for it.  The
basic steps are:

 $ orbit-idl-2 --imodule filename.idl
 $ gcc -fPIC -c filename-imodule.c `pkg-config --cflags ORBit-2.0`
 $ gcc -shared -o filename_module.so filename-imodule.o \
        `pkg-config --libs ORBit-2.0`

You can then install the imodule in $(prefix)/lib/orbit-2.0.

Alternatively, you can install it somewhere else and set the
ORBIT_TYPELIB_PATH environment variable to point at it.

You can then load the typelib with the following python statement:

 >>> ORBit.load_typelib('filename')

This will generate stubs and skeletons for all the types in the IDL
file.


Loading IDL Files
-----------------

Since version 2.6, ORBit2 has had support for generating typelib
information from IDL files at runtime.  PyORBit can make use of this
functionality:

 >>> ORBit.load_file('filename.idl' [, 'cpp arguments'])

As with load_typelib(), this will generate stubs and skeletons.


Automatic Type Discovery
------------------------

If you are only interested in acting as a client (ie. calling
operations on objects), then it may not be necessary to build a
typelib.  ORBit2 includes introspection support that allows PyORBit to
snarf typelib information from an object reference, provided that the
server is implemented with ORBit2.

This makes client side operation almost painless.