Changes in Pyrite 0.9.0
-----------------------

As always, a change in version numbers heralds significant changes in
Pyrite.  The most significant ones are described below:

* User ID as primary identifier

In keeping with the apparent behavior of the Palm Desktop and other
software, Pyrite now uses the numeric user id as the primary
way of identifying a particular palmtop.  The numeric UID is a 4-byte
unsigned integer that is generated, apparently at random, the first
time the palmtop is synchronized to the Palm Desktop.  The Palm
Desktop uses this number as the primary way of identifying a user; the
name is secondary, and may change over the lifetime of the user's
data.

** New data directory layout

The data directory is now organized by UID, with each user's data
being stored in a directory named using the string representation of
the UID.  Thus, my Pyrite data directory looks something like this:

  /home/rob/Palm               - main data directory
             .../22061/        - my palm's user ID
                   .../NAME    - a file containing "Rob Tillotson"
                   .../backup
                   .../install
                   .../Pyrite

The "NAME" file simply contains the user name, and nothing else.
(Only the first line of the file is read, under the assumption that
Palm Desktop compatible user names can't have newlines in them.)

The "Pyrite" directory is new, and will hold Pyrite-specific data.

** Changes to user-related Application object methods

The following Application object methods have been removed:
configure_user, user_add, user_delete, and user_rename.

The following Application object methods have a changed interface:

  user_exists(id) takes a single integer object, the user id, and
    returns true if the data directory has data for this user.

  user_list() returns a list of (id, name) tuples, sorted in id order,
    of all users which exist in the data directory.

  open() can now accept numeric user ids as well as names in 'user:'
    pseudo-urls.

The following Application object methods are new:

  user_lookup(name) returns the id corresponding to the named user, or
    zero if the user is not represented in the data directory.

  connect_user() performs post-connect activities (see below for
    description).  Applications will not call this directly, but in
    some cases overriding it may be useful.

  change_user(id) changes the "current user", reconfiguring plug-ins
    if necessary.  If the given id is not known to Pyrite, an
    exception is raised.

** User-related actions at the start of synchronization

It is no longer necessary (or even allowed) to add users to the Pyrite
data directory by hand, or within an application.  Pyrite will now do
that automatically, the first time a particular palmtop is connected.

Specifically, as soon as a connection is made, Pyrite checks the UID
and user name and proceeds as follows:

  - if both the UID and name are empty, the palmtop is either brand
    new or has been reset.

    Pyrite currently does not handle this situation, but in the near
    future it will do something useful like restore a backup, or
    prompt the user for a new user name and generate a UID.

  - if the palmtop has a name but no UID, it has probably never been
    synchronized with the Palm Desktop.  (The "install-user" command
    from pilot-link does not set a UID unless you specifically provide
    one.)

    In this case, Pyrite assigns a new random UID, and proceeds as
    below.

  - if the palmtop has both a name and UID, it has already been
    identified and it is not necessary for Pyrite to generate a UID.

    If the palmtop has not been synchronized to Pyrite before (i.e. if
    there is no entry for its UID in the data directory), Pyrite will
    create a new directory for it, and populate it accordingly.

    If the palmtop has been synchronized to Pyrite before, but the
    user name does not match the one on the palmtop, Pyrite will
    assume that the name has been changed locally and will update it
    on the palmtop.

In any case, Pyrite will change its "current user" to that of the
palmtop.

If the name or UID of the palmtop has changed as a result of this
process, the changes will be written to the palmtop when the
connection is closed.

* New C module

The old _pdapalm module has been replaced.  The new module, called
"pisock", differs from the old one in several significant ways:

  - The new module's interface is closely based on the raw C interface
    to the pilot-link library.  It does not attempt to put an
    object-oriented wrapper around the pilot-link functions.

  - The new module only handles the DLP and socket related functions
    from the pilot-link library.  It cannot be used for prc/pdb file
    access at present.

  - The new module is built with SWIG, rather than being hand-coded.
    Hopefully this will make maintenance easier and portability
    greater.

  - The new module is under the same license as the rest of Pyrite;
    the old one was LGPLed, due to its derivation from the original
    pilot-link Python binding.  (If this makes a difference to you,
    please don't forget that pilot-link is still LGPLed.)

This change should be invisible to most applications, because it is
hidden behind the Store interface.  For the time being, Pyrite
applications will use the old module if you specify the "--old-dlp"
option on the command line.

The source to the new module is in glue/pisock.i and the
SWIG-generated C source is in glue/pisock_wrap.c.  (The C source is
included so that building Pyrite does not depend on the availability
of SWIG.)  If you want to regenerate the C source, install SWIG then
do something like "swig -python -dnone pisock.i".

* Pure-Python prc/pdb access code is now the default

The pure-Python file access code (in prc.py) is now used by default.
Hopefully this will enhance portability to systems where building the
C modules (or pilot-link) is difficult.

To keep using the old method of accessing local files (for many Pyrite
operations), supply the "--old-pdb" command line option to Pyrite
applications.

* App package renamed to Connector

For the time being, code which loads plug-ins from the "App"
collection will still work (getting the corresponding Connector), but
produce a warning.

The main reason for this change is to reduce confusion.  I have been
working (slowly) on documentation for Pyrite, and I keep running into
problems trying to explain the the difference between the code that
supports a particular palmtop application, and an actual application
on the desktop.  Also, the other plug-in collections have always had
names which can be used as descriptive nouns... but "App" was
completely wrong for that the stuff that is now in the Connector
collection actually does.  With the addition of the Application
collection, this seemed like a good time to pick a new name for "App".


* Applications are now in a plug-in collection

Applications have always been plug-ins; now, there is a collection to
hold them.  This should have no effect on existing code, because the
"Pyrite.Application" package still contains the same stuff it did when
it was only a module.

The addition of the Application collection is just the beginning of a
fairly large change in how Pyrite applications can work.  (Actually,
the change is part of Sulfur, but Pyrite will be the first example of
the new facilities in use.)  Currently, an application is run by
instantiating and calling an Application object; that object has
methods which parse the command line and do other initialization
tasks, before calling the "run" method (which you override to make the
application actually do something useful).  In the new system, a
generic loader will retrieve the Application object from a plug-in
collection and instantiate it *after* processing the initial
arguments.

This system has one main advantage: it separates loading and
initialization from the application code itself.  These are, in
effect, environmental issues the application shouldn't be concerned
with.  Consider command-line argument parsing: what if you want to run
an application in a way that doesn't allow for a command line?  (Two
examples come to mind: a GUI desktop, where you might set initial
options in a dialog box, or a CGI script on the web, where arguments
are placed in a HTML form.)  If the command line parsing code is
tightly coupled to the application, you will have to rewrite that
application to make it work in another environment.

The Sulfur/Application.py module contains classes which form an
application context; the actual context class is actually a mixture of
several pieces (which can be easily replaced) which handle loading and
option parsing.  At the moment, the application context merely loads
the application plug-in, configures it, and runs it.  In the future,
the context will also provide services to the application.


Local Variables:
mode: outline
End: