PalmPython

Copyright 1998 Rob Tillotson <rob@io.com>
Portions Copyright 1998 Kenneth Albanowski <kjahds@kjahds.com>

Please visit <http://www.io.com/~rob/cq/> for program updates.

Please read doc/NEWS; there are important changes in this release, and
you should not install it without understanding them.

Legal Stuff:

  The distribution archive of this package includes two separate
  products: the Python code, written by me, and the pilot-link C
  module, written by Mr. Albanowski and modified by me.  All of it is
  open source software (http://www.opensource.org/) which means you
  are encouraged to use it without cost and distribute it far and
  wide.  Please see the file called "doc/COPYING" for full details.

Introduction:

  Welcome to my re-implementation of a Python interface to the Pilot.
  At its core, this package is based around the _pdapilot.c module
  included with pilot-link, but I have restructured the API to take
  advantage of more Python-isms.  (I may, in the future, re-implement
  the C layer [probably using SWIG], but the Python-level API will
  remain the same.)

Rationale:

  Besides restructuring everything into a Python 1.5 package (import
  PDA.Palm to get the basic stuff, and PDA.Palm.App.<whatever> to get
  application-specific record types, with more subpackages to come), my
  primary goal was to reorganize the way the layers of code relate to
  each other and make it easier to support additional application and
  storage types without duplication of code.

  One of the main features of this package, as in the original, is that
  record typing is 'magic'.  That is, when you open a database, the
  module figures out what kind of database it is (if it is a known type)
  and uses an appropriate application-specific record type.  In the
  original module, the C code took care of this by looking the record
  types up in the Python module's namespace and returning Python
  objects of the appropriate class.

  While this worked reasonably well, it made reorganizing the module
  into a package and adding new application types more difficult
  because of its dependency on a particular Python module.  This is
  also a philosophical issue to some degree, as I believe that the C
  interface to Pilot-Link ought to be universal enough that it can be
  used with any upper layer at all.  I also wanted to provide new
  storage types (eg. a local database with more random-access
  capability than a pi-file, perhaps in dbm format or on a SQL server)
  without having to reinvent a bunch of stuff in Python to duplicate
  the functionality of the C module.

  So, I removed all of the C->Python dependencies except one: all
  functions that store records, appblocks, prefs, and the like still
  take an object as a parameter, calling that object's "pack" method
  to get the necessary raw data.  Eventually I would like to remove
  this dependency too, passing the raw data and other required
  information to the C module as function parameters, but I haven't
  done so yet because it is not as important to the current
  implementation as was removing the other dependencies.

Class Layout and API:

  When you import PDA.Palm, you get everything in DLP.py, so there is
  no need to import it separately.

  The DLP class represents a connection to the Pilot.  You can open a
  connection to the Pilot by creating a DLP object, passing the port
  name as an argument, and starting HotSync on the Pilot.  The DLP
  object has methods which correspond to much of what is in the C
  module.

  You can work with local files using the openFile and createFile
  functions.

  A Database object represents either an open DLP-connected database,
  a local file, or in fact any Pilot database no matter how it is
  stored.  (It does so by reflecting method calls to another object,
  which it contains.)  Database methods are the same as in the C
  module, plus a few extra bits to support more Python-like behavior
  (they act, to some degree, like lists).  Note that since the C
  objects representing files and hotsync-connected databases don't
  actually have exactly the same API, you might want to be prepared to
  catch exceptions if you use the functions which don't overlap (this
  same principle applies to other forms of storage as well).

  Records in the database, and other associated bits and pieces of
  information, are represented by the generic Record, AppBlock,
  SortBlock, Resource, and PrefBlock classes.  If no
  application-specific modules are loaded, the generic classes provide
  access to raw data.  Application-specific modules may subclass
  these, and register the subclasses so that databases are
  automatically registered by type.  (Please see the code for examples
  of how to do this.)

Current Status:

  Please see the file ChangeLog in the root directory of the distribution.

Bugs and Limitations:

  There are undoubtedly many of them.  Please send bug reports to
  <rob@io.com>.


Future Enhancements:

  Documentation.

  More application modules, and more complete support in the ones that
  are already there.  (eg. application preferences)

  A lazy-loading system in which application modules can be
  pre-registered and automatically loaded only when necessary.

  Storage back-ends for local random-access databases (untested),
  DBAPI-compliant SQL servers, etc.

  GUI desktop framework/API/app-specific modules.
