Overview¶

To implement a command-line program using the helper classes in pysyncml.cli, you generally use one of the following approaches:

• Directory based approach:

  With this approach, the items being synchronized are stored in a directory, and different directories can have different application and synchronization profiles. This de-centralized method allows the user to have multiple directories that represent “units of content”; the directory can be moved around as long as it and all of its contents remains together and intact.

  This approach is implemented by subclassing pysyncml.cli.DirectorySyncEngine.

• Local-user based approach:

  A more centralized approach, where the items being synchronized are stored in some host-local per-user location that may or may not be a file-based location. In this case, the user must specifically request a different configuration in order to choose a different synchronization profile. For example, this could be used when synchronizing the settings of another application that are stored in a pre-defined user-specific directory, such as “~/.config/libreoffice”.

  This approach is implemented by subclassing pysyncml.cli.LocalUserSyncEngine.

Once the right approach is found, then the following steps are required:

1. Subclass a SyncEngine:

   Subclass the appropriate SyncEngine implementation and add any relevant hooks.

2. Implement an Agent:

   Provide a pysyncml.Agent implementation, which primarily exposes CRUD access to your data.

3. Launch the SyncEngine:

   Invoke your SyncEngine‘s run() method and tie in execution entrypoints.

Subclass a SyncEngine¶

The base class CommandLineSyncEngine constructor accepts several parameters which control the profile of the SyncML adapter. These parameters are typically only used as default parameters, when they cannot be loaded from a previous call to the engine.

The following example illustrates a typical subclass of the directory-based approach:

import sqlalchemy as sa
import pysyncml
import pysyncml.cli

class MySyncEngine(pysyncml.cli.DirectorySyncEngine):

  def __init__(self):
    super(NotesEngine, self).__init__(
      appLabel          = '...',           # a short label used to identify this program
      appDisplay        = '...',           # a user-friendly title of this program
      devinfoParams     = dict(...),       # default local device information
      storeParams       = dict(...),       # default local datastore information
      agent             = MyAgent(self),   # a reference to the local Agent
      )

  @pysyncml.cli.hook('model.setup.extend')
  def _createDataItemModel(self):
    # extend the self.model to include any persistent data objects that
    # this engine requires to maintain state, using the self.model.DatabaseObject
    # SQLAlchemy declarative_base class as a base class. an example:
    class MyDataItem(self.model.DatabaseObject):
      # NOTE: an `id` attribute (a UUID string) is provided by the ORM
      data = sa.Column(sa.Text)
    self.model.MyDataItem = MyDataItem

  @pysyncml.cli.hook('adapter.create.store')
  def _scanDataItems(self, context, adapter, store):
    # adding a hook to when the pysyncml store is created to detect changes
    # in the local datastore and register them on the store, for example:
    self.agent.scan(store)

The following table details all the hooks that are available and when they are called. In general, they fall into one of four categories:

• options.setup:

  These are called once during program initialization to setup the options that this program can accept on the command line.

• options.parse:

  These are called once during program start-up to parse the options specified on the command line and to do preliminary SyncEngine configuration. The options are actually parsed twice: once to determine the data directory, and a second time within the context of the data directory.

• options.persist:

  These hooks are called to affect the serialization and de-serialization of options to the data directory so that appropriate data defaults can be persisted.

• model.setup:

  These are called once after program start-up to configure the program’s data model, check the integrity of the database and any schema versioning, and apply any data migrations if needed.

  TODO: integrity checking, schema versioning and data migrations are not implemented yet.

• adapter.create:

  These are called any time the SyncEngine needs a SyncML Adapter. Generally speaking, in client-mode they will be called once when starting the transaction with a remote peer and in server-mode, they will be called for every request from the client (note that there will be multiple requests were synchronization session).

Implement an Agent¶

The pysyncml.Agent provides the binding between the pysyncml SyncML synchronization engine and your data. As pysyncml treats your data as opaque objects, you need to implement all CRUD operations and a limited set of other optional functions (especially when handling hierarchical data).

A stripped-down minimal API with typical functionality follows — see Module: pysyncml.agents for details:

import pysyncml

class MyAgent(pysyncml.Agent):

  # An agent must declare what content types it can de/serialize,
  # which must be a list of pysyncml.ContentTypeInfo objects.
  contentTypes = [ pysyncml.ContentTypeInfo('text/plain', 1.0, preferred=True) ]

  # The above MySyncEngine called the Agent constructor with itself
  def __init__(self, engine, *args, **kw):
    super(MyAgent, self).__init__(*args, **kw)
    self.engine = engine

  # An agent must be able to serialize and deserialize items
  def dumpItem(self, item, stream, contentType=None, version=None):
    # Usually, just invokes the item's dump method (if it has one):
    return item.dump(stream, contentType, version)

  def loadItem(self, stream, contentType=None, version=None):
    # Usually, just invokes the item's load method (if it has one):
    return self.engine.model.MyDataItem.load(stream, contentType, version)

  # An agent must be able to list, add, fetch, modify and delete items
  def getAllItems(self): ...
  def addItem(self, item): ...
  def getItem(self, itemID): ...
  def replaceItem(self, item, reportChanges): ...
  def deleteItem(self, itemID): ...

  # If an agent will also support matching, merging and conflict resolution
  # (only used when run as server), then it must also implement mergeItems,
  # and optionally matchItems (to make it more efficient than the default
  # implementation).
  def mergeItems(self, localItem, remoteItem, changeSpec): ...
  def matchItem(self, item): ...

Launch the SyncEngine¶

This is the easy part... cut-n-paste the following to make your python file executable as well as providing a main entrypoint (which can be used in the entry_points definition of your setup.py file):

def main(argv=None):
  engine = MySyncEngine()
  return engine.configure(argv).run()
if __name__ == '__main__':
  sys.exit(main())

Example Implementation¶

See Sample Implementation: sync-notes for an example of a real-world program provided by the pysyncml package that uses the pysyncml.cli functionality.