PYME.config module

Support for configuration / settings in PYME. This will eventually replace a motley collection of different ways of storing the configuration in use in different parts of PYME. Configuration is read from the following locations (if they exist) which are searched in order, with later entries over-riding prior ones:

  • an etc/PYME directory under the python sys.prefix. This would usually be /usr/local/ under standard unix python and the distribution base directory for a distribution such as anaconda. This allows installation wide configuration and is also a place that should be writable when installing conda packages and the like (useful for writing a package with plugins which register themselves - see plugin functions below.
  • a machine wide /etc/PYME directory. This is included for compatibility, but it is not envisaged that this will be used often, as it will only work on posix systems while the the above {{sys.prefix}}/etc/PYME option will also work under windows.
  • a .PYME directory under the users home directory. This should be used for user specific settings.

Within each configuration directory there can be a config.yaml file which stores configuration settings as key-value pairs. These are accessed using the get() function.

The directories may also contain a plugins folder, which in turn can contain subfolders for visgui, dsviewer, and recipes. PYME will also detect custom acquisition protocols saved in the .PYME/protocols directory, similarly init scripts will be detected in .PYME/init_scripts directory. The overall template for a configuration directory is as follows:

.PYME
  |- config.yaml
  |- plugins
  |     |- visgui
  |     |     |- somemodule.txt
  |     |     |- anothermodule.txt
  |     |
  |     |- dsviewer
  |     |     |- somemodule.txt
  |     |
  |     |- recipes
  |           |- anothermodule.txt
  |
  |- protocols
  |     |- a_protocol.py
  |     |- another_protocol.py
  |
  |- init_scripts
        |- init_mymachine.py
        |- init_my_other_config.py

If you want to verify which directories will be searched on your particular python installation, running the following on the command line will tell you:

python -c "import PYME.config;print PYME.config.config_dirs"

with anaconda on OSX this gives me:

['/Users/david/.PYME', '/etc/PYME', '/Users/david/anaconda/etc/PYME']

Examples

config.yaml

The config.yaml file is essentially nothing more than a set of keys and values separated by colons. List and dictionary parameter values are supported using standard yaml notation.

dataserver-root: "/Users/david/srvtest/test1"
h5f-flush_interval: 1
PYMEAcquire-extra_init_dir: "C:/pyme-init-scripts"

plugins/visgui/PYME.txt

If we were to use the plugin architecture to register some of the native plugins (rather than using explicit knowledge of their locations), the registration file would look something like this. Each line is a fully qualified module import path.

PYME.LMVis.Extras.photophysics
PYME.LMVis.Extras.particleTracking

In addition to the configuration derived from config.yaml, a few legacy environment variables are recognized. Subpackages are also permitted to save configuration files in the .PYME directory.

Functions

PYME.config.get(key, default=None)

Gets a configuration parameter, by name

Parameters:

key : basestring

The parameter name

default : unspecified, optional

The default value you want to assume if the parameter is undefined.

Returns:

The parameter value, or the default value if undefined.

PYME.config.get_custom_protocols()

Get a dictionary recording the locations of any custom protocols.

Returns:A dictionary of {basename : full path} for any protocols found.
PYME.config.get_init_filename(filename, legacy_scripts_directory=None)

Look for an init file in the various locations. If the given filename exists (i.e. is a fully resolved path) it will be used. Otherwise ‘init_scripts’ subdirectory of the configuration directories will be searched, in order of precedence user - site - dist. It also checks for files in a provided directory (to support legacy usage with the PYMEAcquire/scripts directory) and the config option PYMEAcquire-extra_init_dir.

Parameters:

filename: init file name to locate in script dirs

Returns:

If found returns first match as full path to init file

returns None if not found.

PYME.config.get_plugins(application)

Get a list of plugins for a given application

Modules are registered by adding fully resolved module paths (one per line) to a text file in the relevant directory. The code searches all files in the relevant directories, and the intention is that there is one registration file for each standalone package that provides modules and can e.g. be conda or pip-installed which contains a list of all the plugins that package provides. The registration filename should ideally be the same as the package name, although further subdivision for large packages is fine. registration filenames should however be unique - e.g. by prefixing with the package name. By structuring it this way, a package can add this file to the anaconda/etc/PYME/plugins/XXX/ folder through the standard conda packaging tools and it will be automatically discovered without conflicts

Parameters:

application : basestring

One of ‘visgui’, ‘dsviewer’, or ‘recipes’

Returns:

list of fully resolved module paths