pysyncml 0.1 documentation

Module: pysyncml.cli

«  Module: pysyncml.change.tracker   ::   Contents   ::   Module: pysyncml.context  »

Module: pysyncml.cli

The pysyncml.cli.base is a helper module that provides commonly used functionality when implementing a pysyncml command line interface synchronization engine.

class pysyncml.cli.base.CommandLineSyncEngine(appLabel=None, appDisplay=None, appModelVersion=None, defaultDevID=None, defaultListen=80, devinfoParams={}, storeParams={}, agent=None, hooks=None, *args, **kw)[source]

The CommandLineEngine class helps ease the burden of creating a command line sync engine by implementing the following functionality:

  • Selection and allocation of pysyncml storage repository.
  • Generation of an extensible sqlalchemy model.
  • Support for client-side and/or server-side operation.
  • Configuration of commonly used command line options.

There are different subclasses that exist to support different operation styles:

  • DirectorySyncEngine:

    A directory-based approach, where the items being synchronized are stored in a directory, and different directories can have different application and synchronization profiles.

  • LocalUserSyncEngine:

    A more centralized approach, where the items being synchronized are stored in some host-local per-user location (for example, in another application’s settings). In this case, the user must specifically request a different configuration in order to choose a different application or synchronization profile.

The CommandLineClient base constructor accepts the following parameters:

  • appLabel

    A short unique identifier for this application, typically set to the program’s name, for example “sync-notes”. This label should not contain any special characters, especially those that are not allowed as part of a filename. Amongst other things, it is used to:

    • generate the default device ID, if not specified,
    • create application-specific configuration directory/file names,
    • default datastore URI,
    • and much more.
  • appDisplay – The name of the application when displayed to the user, for example “Note Synchronizer”.

The CommandLineClient also has the following additional attributes:

Parameters:dataDir – The directory that contains all of the database files - this is usually taken care of by one of the pre-existing subclasses. It is expected to end with a “/”.

TODO: document all options...

addHook(name, callable)[source]

Subscribes callable to listen to events of name type. The parameters passed to callable are dependent on the specific event being triggered.


Configures this engine based on the options array passed into argv. If argv is None, then sys.argv is used instead. During configuration, the command line options are merged with previously stored values. Then the logging subsystem and the database model are initialized, and all storable settings are serialized to configurations files.

run(stdout=<open file '<stdout>', mode 'w' at 0x40253070>, stderr=<open file '<stderr>', mode 'w' at 0x402530c0>)[source]

Runs this SyncEngine by executing one of the following functions (as controlled by command-line options or stored parameters):

  • Display local pending changes.
  • Describe local configuration.
  • Run an HTTP server and engage server-side mode.
  • Connect to a remote SyncML peer and engage client-side mode.

NOTE: when running in the first two modes, all database interactions are rolled back in order to keep the SyncEngine idempotent.

class pysyncml.cli.base.DirectorySyncEngine(syncSubdir='.sync', defaultDir=None, *args, **kw)[source]

The DirectorySyncEngine is a helper peer environment where synchronized items are stored in a directory (or subdirectories thereof). A special (configurable) .sync subdirectory is created to contain configuration, state and synchronization data, which must be ignored by the calling framework. Moving the directory and its contents, as a unit, will not affect the functionality of the sync.

In addition to the CommandLineSyncEngine constructor parameters, the DirectorySyncEngine accepts the following:

  • syncSubdir – Specifies the name of the immediate subdirectory of the base directory that should be created to contain configuration, state and synchronization data. Removal of this directory will reset all client/server states, and synchronization will need to resume via a “slow-sync”. The application should ignore this directory when manipulating any data. The default is ".sync".
  • defaultDir – If specified, will allow the user to invoke the application without needing to identify the directory to synchronize, and instead will default to this value. If used, this CommandLineSyncEngine begins to resemble how the LocalUserSyncEngine operates, but diverges in the fact that the synchronization data is kept in the same directory as the synchronized items.

In addition to the CommandLineSyncEngine attributes, the DirectorySyncEngine also provides the following:

Parameters:rootDir – The path (potentially either relative or absolute) to the directory under control by this synchronization engine. The path, if valid, ends with a slash (“/”).

Decorator used to tag a method that should be used as a hook for the specified name hook type.

«  Module: pysyncml.change.tracker   ::   Contents   ::   Module: pysyncml.context  »