head	1.4;
access;
symbols;
locks; strict;
comment	@# @;


1.4
date	2001.04.02.03.31.41;	author tack;	state dead;
branches;
next	1.3;

1.3
date	2001.03.29.13.05.12;	author tack;	state Exp;
branches;
next	1.2;

1.2
date	2001.03.29.05.33.04;	author tack;	state Exp;
branches;
next	1.1;

1.1
date	2001.03.29.04.14.01;	author tack;	state Exp;
branches;
next	;


desc
@@


1.4
log
@Updated README and removed DOCS
@
text
@- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Documentation: Python bindings for ORBit                 ORBit-Python 0.2.0
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Introduction
============

Dynamic IDL Compiling
=====================

Python is a dynamic language, so why not take advantage of it?  O-P doesn't
use stubs or skeletons like most other ORBs, but instead compiles IDL files
at run-time.  This means incremental design and rapid prototyping can be
done easily and quickly.

The function CORBA._load_idl() is used to load a specific IDL file.  Other
ORBs don't implement this function, of course, so in order for code to be
portable from these ORBs, an alternative approach must be used.  This
approach is called "IDL preprocessing."  When the CORBA module is imported
for the first time, it scans a list of directories, naively (and quickly)
parsing each IDL file to discover what modules and interfaces the IDL files
provide.  This list of directories is specified in the IDLPATH environment
variable.  If IDLPATH is unset, O-P defaults to the current directory, and
the system IDL directories if they exist (/usr/share/idl and
/usr/local/share/idl).

O-P hooks the import function to determine if the requested module exists
in an IDL file.  If it does, the IDL file is automatically parsed (using
libIDL), processed into corresponding Python objects, and imported into the
caller's namespace.

When an IDL module is being imported, O-P attempts to make intelligent
decisions about which files to actually parse using libIDL.  For example,
if you import Bonobo, O-P really only needs to process Bonobo.idl, and not
the dozen or so other Bonobo_* files.  In most cases, O-P's algorithms to
narrow the list of IDL files for a module are sufficient, but sometimes
they'll fail.  If this happens to you, please report it as a bug.  As a
work-around, you can use CORBA._load_idl() to load the correct file(s), and
then import the module.

Because O-P uses libIDL to handle IDL files, it must define __ORBIT_IDL__
when parsing.  In some cases, other defines must be made in order to
properly load certain modules, such as GNOME::ObjectFactory.  If we look at
oaf-factory.idl, we see:

   #if !defined(GNOME_FACTORY_COMPILATION) && defined(__ORBIT_IDL__)
   %{
   #pragma include_defs liboaf/oaf-factory.h
   #pragma include_defs liboaf/oaf-factory-suppress.h
   %}
   #pragma inhibit push
   #endif

The "pragma inhibit push" tells the parser to skip everything until it sees
a "pragma inhibit pop."  So we see that we have to somehow define
GNOME_FACTORY_COMPILATION in order to import this module.  First let's see
what happens if we don't:

   >>> import CORBA
   >>> from GNOME import ObjectFactory
   Traceback (innermost last):
     File "<stdin>", line 1, in ?
   ImportError: No module named GNOME

What actually happened here?  The error is a bit misleading.  O-P knows
from the IDL preprocessing stage that it must auto-load oaf-factory.idl, so
it does.  Because GNOME_FACTORY_COMPILATION is undefined, the actual module
definition never gets parsed, and the Python objects for that module never
get created.  Python tries to import GNOME.ObjectFactory and it fails.

To fix that, we need to use another O-P extension: CORBA._libidl_args.
The _libidl_args attribute is a list containing all arguments that will be
passed to the IDL processing step (from libIDL).  The default is
-D__ORBIT_IDL__ as well as the include paths specified by the IDLPATH
variable.  Let's see:

   >>> import CORBA
   >>> CORBA._libidl_args
   ['-D__ORBIT_IDL__', '-I/usr/share/idl']

We need to append -DGNOME_FACTORY_COMPILATION to this list before we can
import GNOME.ObjectFactory:

   >>> import CORBA
   >>> CORBA._libidl_args.append("-DGNOME_FACTORY_COMPILATION")
   >>> from GNOME import ObjectFactory
   >>> ObjectFactory
   <class GNOME.ObjectFactory at 80eecb8>

Note that modifying _libidl_args needs to be done before you import any
IDL modules.  


The API
=======

CORBA
-----

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

ORB_init(argv, orb_identifier)

   Arguments:
      argv: (list) argument list to pass to the ORB
      orb_identifier: (string) Specifies the type of ORB

   Description:
      Initialize the ORB and return a CORBA.ORB object.

   Example:
      import sys, CORBA
      orb = CORBA.ORB_init(sys.argv, CORBA.ORB_ID)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   
_load_idl(filename)

   Arguments:
      filename: (string) file to dynamically load

   Description:
      Forces O-P to load and parse the specified file.

   Example:
      import CORBA
      CORBA._load_idl("/usr/share/idl/oaf.idl")

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

TypeCode(repoid)

   Arguments:
      repoid: (string or CORBA.Object) If a string is specified, is is the
              repository id of the requested typecode.  If an object is
              given, it must be a CORBA.Object, in which case a typecode
              object is created based on the repository id of the given
              object.

   Description:
      Creates a type code object (CORBA.TypeCode) based on the given 
      argument.

   Example:
      import CORBA
      CORBA.TypeCode("IDL:CORBA/String:1.0")

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Any(typecode, value)

   Arguments:
      typecode: (CORBA.TypeCode) specifies the type of the value argument
      value: (object) an object of the type given by typecode

   Description:
      Creates a CORBA.Any object of the type 'typecode' whose value is
      given with 'value.'  CORBA.Any objects can represent any CORBA
      object.

   Example:
      import CORBA
      CORBA.Any( CORBA.TypeCode("IDL:CORBA/String:1.0"), "foobarbaz!" )

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

@


1.3
log
@Added forward decl support
@
text
@@


1.2
log
@More documentation
@
text
@d27 1
a27 1
O-P hooks the import function to determine of the requested module exists
d54 1
a54 1
The "pragma inhibit push" tells the parse to skip everything until it sees
@


1.1
log
@Working on documentation.  Ugh
@
text
@d8 158
@

