Client interface

A client is any software component interacting with a daemon, in the form of issuing requests, receiving responses to requests, and receiving asynchronous updates of new item values. The Python interface described here makes liberal use of background threads, callbacks in particular can and will arrive from background threads as asynchronous updates arrive.

Unlike the Daemon interface, a typical client application will not need subclasses of the classes defined here, they are expected to be used directly, as-is.

Getting started

mKTL will cache information locally; there are no restrictions on where this information gets cached, other than it needs to be cached somewhere. The default location for this cache is:

$HOME/.mKTL

You can override this location by setting the MKTL_HOME environment variable to the absolute path of your choice; any directory specified in this fashion will be created if it does not already exist. Alternatively, the program may invoke the mktl.home() method to specify the location at run time.

mktl.home(default=None)

Return the directory location where we should be loading and/or saving configuration files. This defaults to $HOME/.mKTL, but can be overridden by calling this method with a valid path, or by setting the MKTL_HOME environment variable. Note that changes to the environment variable will be ignored unless it is set prior to the first invocation of this method.

You may need to pre-populate your local cache with information from the registries handling the configuration for the store(s) you wish to access. The mk command line tool will handle this process; for a given IP address or hostname, you would invoke:

mk discover 192.168.5.34

This discovery process will query that address for any available configurations, but more importantly, will cache the address of that registry and use it again in the future if/when discovering new services, without an explicit request to do so. In other words, it should only be necessary to run this discovery process a single time in order to gain access to a new set of mKTL stores.

The mktl.get() method is the universal entry point to retrieve a mktl.Store or mktl.Item instance; client configuration is automatically refreshed if necessary, and the remainder of the connection logic is handled by the mktl.Store.

All other client operations, such as getting and setting item values, are handled via the mktl.Item instance.

mktl.get(store, key=None)

The get() method is intended to be the primary entry point for all interactions with a key/value store.

The return value is either a cached Store or Item instance. If both a store and a key are specified, the requested item will be returned from the specified store. The same will occur if the sole argument is a store and key name concatenated with a dot (store.KEY). A Store instance will be returned if the sole argument provided is a store name. Both the store and the key are case-insensitive, all arguments are translated to lower case before proceeding.

If the caller always uses get() to retrieve a Store or Item they will always receive the same instance of that class. In that sense, get() is a factory method enforcing a singleton pattern.