Title:   The Python Language Interface
Status:  Current 
Created: 2003-09-16
Revised: 2006-03-24

TODO: This technote should be merged into the devguide and into Epydoc
docstrings.

The Python Language Interface enables you to use GNUe Appserver business
objects in python code as if they were python objects.


Obtaining a Session Object
==========================

The Python Language Interface can be used in three ways:
a) in standalone programs using appserver as a kind of library
b) in the code of appserver
c) in procedures of business objects.

Standalone Programs
--------------------
* First, "from gnue.appserver.language import App"
* Then, at the very start of your program, create an application object using a
  command like "app = App.App ()"
* Use the command "session = app.newSession (username, password) to create a
  session. This will "log" you into appserver.
  Notice that this is not a real login into a running instance of appserver.
  Instead, this just simulates an appserver running on the local machine.
  Therefore, you don't need a running appserver process. This will probably
  change in the future.
* The session object you get from newSession can be used as described below.

Appserver Internal Code
-----------------------
Appserver maintains an internal session that should be used for all internal
access to business objects. This internal session is created at appserver
startup and can at any time be obtained using the following two lines:
  from gnue.appserver.language import Session
  session = Session.InternalSession ()

Procedures of Business Objects 
------------------------------
Procedures will run as a method of a business object and therefore receive an
instance of a business object as the "self" parameter. Besides this every
procedure has access to three global methods "find", "new" and "setcontext"
(see below).


Using the Session Object
========================

The session object knows the following methods:
* setcontext (context): 
  Set the current module context. All not fully qualified identifiers will be
  qualified with this context. 
* qualify (name): 
  If 'name' is not fully qualified, it will be completed using the current
  context. If no context is specified (using setcontext) an exception will be
  raised.
* close (): 
  Close the connection, log out from the server.
* commit (): 
  Commit the current transaction.
* rollback (): 
  Undo the current transaction.
* find (classname, conditions, sortorder, properties): 
  Return a list of objects that fulfill the conditions (TODO: describe the
  format of this parameter). "sortorder" is a list of strings (property names)
  that define the sort order of the returned list.  "properties" is a list of
  strings (property names) that define the properties that should be preloaded
  from the database. Access to properties listed here will be much faster
  afterwards than access to properties not listed, because the latter cause a
  new query to the database. The return value of this method is virutally a
  list of business objects. 
* new (classname): 
  Create a new (empty) instance of the given class and return it.
* get (classname, objectId):
  Return the instance with the given object id.
* message (messageName, *args):
  Return the message from the message catalogue.


Using Lists of Business Objects
===============================

Lists of business objects (as returned by the find () method of the session
object) can be regarded as normal Python lists. Especially list[i], len(list)
should work. Other list functions might be added later. list[i] will return a
business object. These lists are immutable.


Using Business Objects
======================

The Language Interface allows handling a business object like a normal Python
object.

Every business object has a property "objectId" that holds it's object id (the
value of "gnue_id") or None if the object has not yet been stored.

Apart from that, you can access all properties of the business object like
python properties, i.e. by using object.propertyname. You can read these
properties as well as assign values to them.
Properties defined in the class repository as "string" will be treated as
Python type "string", properties defined as "number" will be Python type
"float" if they have a fractional part and of type "int" otherwise.
Properties defined as type "id" (that is, the gnue_id properties)
are treated as Python type "string". Properties defined as "date", "time" or
"datetime" will be treated as Python DateTime objects and "booleans" are
handled as Python boolean values. 

Properties of other types than listed before are treated as "reference
properties" and theirfor they will return the busienss object they point to.

A string representation (using the str() function) of a business object returns
it's object-ID mentioned before.

If you change the values of properties in a business object, it will call an
implicit store () in the session manager. That's why there is no store ()
method in the business object itself.

Every business object has the method "delete" to destroy the object.
Notice that you also have to call the "commit" method of the session object to
make deletion of the object persistent.
