2.4. vacumm.config – Configuration of modules

2.6. Content

Utilities to manage VACUMM basic configuration of modules

class URLLibProgressBar(width=80)[source]

Progress bar compatible with urllib.urlretrieve()

It looks like:

[=======>        22%                  ]
Example:
>>> import urllib
>>> mybar = URLProgress(width=50)
>>> urllib.urlretrieve("http://web.net/file", "myfile", reporthook=mybar)
Inspired from:

http://code.activestate.com/recipes/168639-progress-bar-class/
check_data_file(section, option, parent_section=None, parent_option=None, quiet=None, suffix=None, avail=False, check_license=True)[source]

Check the existence of a file whose path is stored in a configuration file

Two cases are treated:

  1. Path value is accessible from the vacumm configuration (get_config()), using section (module name) and option.
  2. Path value is accessible from a secondary configuration file using parent_section (module name) and parent_option, and the path value of this config file is accessible from the vacumm configuration using section and name.

If the file is not found, it may download it using an url whose value is accessible at the same place as the path and with the same option name + ‘_url’.

Tasks:
  1. If suffix is a list, call itself in a loop with suffix set to each element of the list.
  2. Get the path, url and license of the data file.
  3. If avail is True, only check the existence and return the status.
  4. If the file is not found (and quiet is False), ask the user for it. If the path specified is empty, simply go further. If is not empty, update the configuration and return it, else raise an error.
  5. If a license info is present, tell the user that he must have the authorization to download it. If the user does not agree, raise an error.
  6. Ask the user where to download the file using get_dl_dir().
  7. Download the file using download_file().
  8. Update the configuration if needed.
  9. Return the path.
Params:
  • section: Section where to find the path to data.
  • option: Option to read the path.
  • parent_section, optional: Section of the vacumm configuration where to find the path to the secondary configuration file that has the path stored within.
  • parent_option, optional: Option of the vacumm configuration to read the path to the secondary configuration.
  • quiet, optional: Don’t ask question about where to download the file, don’t display any info, don’t ask for authorization.
  • suffix, optional: A suffix or a list of suffixes to append to the path and url before using it.
  • check_license, optional: If a license info is found, show ot and ask the user if he has autorization for downloading it.
  • avail, optional: Check availability only (see below).
Return:

  • A single path or a list of paths.

  • None or a list of them if nothing found.

  • If avail=True:

    • 0: Data file not on disk and not downloadable (however, user can specify the path manually).
    • 1: File is not on disk, but downloadable.
    • 2: File is on disk.
Examples:
>>> check_data_file('vacumm.bathy.shorelines', 'shapefile_histolitt', suffix=['.shp', '.dbf'])
>>> check_data_file('etopo2', 'file', parent_section='vacumm.bathy.bathy',
... parent_option='cfgfile_gridded')
data_sample(data_file, mode='all')[source]

Transform the relative path of a sample file to an absolute path

This can be either in the VACUMM data directory (get_data_dir()), or in the UVCDAT data directory.

Params:

  • data_file: File basename.

  • mode, optional:

    • "all" or None: Look first into VACUMM dir then and into UVCDAT dir if not found. If finally not found, return the VACUMM sample path.
    • "vacumm": Look only into the VACUMM data dir only.
    • "uvcdat": Look only into the UVCDAT data dir only.
download_file(url, locfile, quiet=False)[source]

Download a file with a progress bar using urllib.urlretrieve()

edit_file(fname, editor=None, verbose=True)[source]

Edit a file

Params:
  • fname: File name.
  • editor, optional: Editor to use (default to VISUAL or EDITOR.
Source:

Mercurial code
edit_user_conf_file(fname='vacumm.cfg', editor=None, verbose=True)[source]

Edit the user configuration file

Params:
  • fname, optional: Relative file name, which defaults to vacumm.cfg.
  • editor, optional: Editor to use (default to VISUAL or EDITOR.

Examples:

>>> edit_user_conf_file()
>>> edit_user_conf_file('my_other_config.cfg', editor='gedit')
See also:edit_file() and get_user_conf_file()
get_com_conf_dir()[source]

Get directory of common alternate configuration files

These files are not included in the distribution. They have a similar role to user config files but they are accessible to all users. This directory can be at two different places, depending on if the library is an installed version or developers version.

  • If installed : in vacumm-config subdirectory in the installed package directory (see get_lib_dir()).
  • Else in the config subdirectory of the main distribution tree (see get_dist_dir()).
get_com_conf_file()[source]

Get common user configuration file

Shortcut for:

os.path.join(get_com_conf_dir(), 'vacumm.cfg')
See also:get_com_conf_dir(), get_user_conf_file()
get_config(section=None, user=True, asstring=False, cfg=None, parent_section=None, parent_option=None, split=False)[source]

Get a ConfigParser.SafeConfigParser instance of current configuration or as a string

Params:
  • section, optional: A module or its name, or "__all__" to get a full config (config files in module drectories are also scanned).
  • user, optional: Also scan available user configuration files.
  • asstring, optional: Get it as string.
  • parent_section/option, optional: Section (module name) and option of the main vacumm configuration that give the path to the target configuration file. If not provided, it uses cfg the main vacumm configuration.
See also:

get_config_files()
get_config_files(section=None, check=False, user=1)[source]

Get the list of configuration files that can be loaded

It lists all configuration files that should be loaded to search for a configuration value. It first list default configuration files, then add user specific files.

Params:
  • section, optional: Target section of the configuration files. It is generally a module name. In this case, user and default configuration files located in the where the module is are inserted into the list. It can also be a list of module name. Eventually, if the special value "__all__" is passed, it searches for all configuration files named vacumm.cfg in the whole library tree.
  • user, optional: If False or 0, load only default config. If 1 or True, append user configuration files to the list. If 2, list only user config files.
Example:

Suppose you are in directory /home/me/myproject, get_config_files() is called from module vacumm.bathy.shorelines, and your use VACUMM as a developper, i.e. the library is not installed but used directly in the installation tree whose path is /home/me/python/vacumm:

>>> get_config_files('vacumm.bathy.shorelines')

The following list is returned :

  1. /home/me/python/vacumm/lib/python/vacumm/bathy/shorelines/vacumm.cfg (defaults)
  2. /home/me/python/vacumm/lib/python/vacumm/vacumm-config/vacumm.cfg (defaults)
  3. /home/me/.config/vacumm/vacumm.cfg

Content of last files overides content of first files.

Other usages:

>>> get_config_files('__all__', user=False)
>>> get_config_files(['toto.tutu', 'tutu.tata'])
get_config_sections(cfg=None, parent_section=None, parent_option=None, getcfg=False)[source]

Get sections names

Params:
  • parent_section/option, optional: Section (module name) and option of the main vacumm configuration that give the path to the target configuration file. If not provided, it uses cfg the main vacumm configuration.
  • getcfg, optional: Also return the configurations object.
get_config_value(section, option, regexp=False, ispath=False, user=True, expand=True, vars=None, raw=False, umode='auto', cfg=None, getcfg=False, parent_section=None, parent_option=None)[source]

Get the a config value in available VACUMM configuration files

The list of possible configuration files is provided by get_config_files().

Configuration values can use expanded variables in two ways:

  1. Internal option name are automatically expanded to their value if found in the form %(option_name)s. In addition to internal options, you can provide your own (var_name,value) pairs by passing a dictionary to the vars keyword. Some external options pointing to directory names are provided automatically (but can be overidden):

  2. User home ~ and environement variable (in the form ${HOME} are expanded if keyword expand is set to True.

Params:

  • section: A section in the config, typically a full module name (see get_config_files())

  • option: Option to read in the section.

  • regexp, optional: option is interpreted a regular expression. If True, it returns a dictionary of (option,value) items found.

  • ispath, optional: if True, value is converted using numpy.distutils.misc_util.allpath().

  • vars, optional: Dictionary used to expand variables in the form %(var_name)s.

  • user, optional: Also scan user files. If raw is True, value with conf_dir expanded using user_conf_dir, and if differents values are found, they are treated depending on mode.

  • umode, optional: If user is True, and two possible values are found (one with conf_dir, one with user_conf_dir), they are treated depending on umode:

    • "merge": Value found using user_conf_dir has priority over value found using conf_dir.
    • "all": A two-element list is returned if elements are different.
    • Else, if value seems to be a config file (ending with “.ini” or “.cfg”), mode="all" else mode="merge".

  • cfg, optional: External ConfigParser.ConfigParser instance or an external config file. If not provided, configuration is given by get_config() (internal configuration).
Returns:

If regexp is `` False``, return the value or None if not found, else return a dictionary.
Example:
>>> path = get_config_value('vacumm.bathy.shorelines', 'shapefile_histolitt')
>>> paths = get_config_value('vacumm.bathy.shorelines', 'shapefile_.*', regexp=True)
>>> paths = get_config_value('my.module', vars=dict(mydir='/home/me/dir'))
get_data_dir(raiseerr=False)[source]

Get the data directory absolute path

This directory contains data samples and other needed files. It can be at two different places, depending on if the library is an installed version or a developers version.

  • If installed : in vacumm-data subdirectory in the installed package directory (see get_lib_dir()).
  • Else in the data subdirectory of the main distribution tree (see get_dist_dir()).

Warning

It raises an VACUMMError error if not found and if raiseerr is True, else return ‘’.

get_default_config(section='__all__')[source]

Shortcut to:

get_config(section='__all__', user=False)
get_dir_dict(modname=None)[source]

Get the following directory names as a dictionary

Params:
  • modname, optional: Module name.
get_dist_dir()[source]

Upper directory of VACUMM distribution tree or None for an installed package

get_dl_dir(suggest=None, filedesc=None, quiet=False)[source]

Get the download directory

get_home_conf_dir()[source]

Get the directory which contains the user config dir

It defaults to ~/.config and may be set with the XDG_CONFIG_HOME environmement variable.

get_lib_dir()[source]

Directory of the vacumm package

get_scripts_dir(subdir=None, raiseerr=False)[source]

Get the scripts directory absolute path

This directory contains examples of script. It can be at two different places, depending on if the library is an installed version or a developers version.

  • If installed : in vacumm-scripts subdirectory in the installed package directory (see get_lib_dir()).
  • Else in the scripts subdirectory of the main distribution tree (see get_dist_dir()).

Warning

It raises an VACUMMError error if not found and if raiseerr is True.

get_tut_dir(raiseerr=False)[source]

Get the tutorials directory absolute path

This directory contains all tutorials used by the documentation. It can be at two different places, depending on if the library is an installed version or developers version.

  • If installed : in vacumm-scripts/tutorials subdirectory in the installed package directory (see get_lib_dir()).
  • Else in the scripts/tutorials subdirectory of the main distribution tree (see get_dist_dir()).

Warning

It raises an VACUMMError error if not found and if raiseerr is True.

get_user_conf_dir()[source]

Get directory that contains user configuration files

This directory contains main and secondary configuration files. These files are usually referenced in the general configuration file. On linux, it should be ~/.config/vacumm. It may be set with the VACUMM_CONFIG_DIR.

get_user_conf_file(fname=None)[source]

Get main user configuration file

Params:
  • fname, optional: Relative or absolute file name. It may be set with the VACUMM_CONFIG_FILE. The config directory is prepended if the file name is relative.

Shortcut for:

os.path.join(get_user_conf_dir(), fname)
See also:get_user_conf_dir(), edit_user_conf_file()
handle_edit_args(args)[source]

Handle argparse args from vacumm_config.py edit ...

handle_print_args(args)[source]

Handle argparse args from vacumm_config.py print ...

load_configs(cfgfiles)[source]

Read configuration files in merged and separate configuations

Params:

  • cfgfiles: Configuration files.

    • If a file, simply return the associated SafeConfigParser instance.
    • If a list of files, does the same merging all the files.
    • If a tuple, create a configuration for each of its elements.
Example:
>>> cfg = load_configs('myfile.cfg')
>>> cfg = load_configs(['myfile1.cfg', 'myfile2.cfg'])
>>> cfg1, cfg2 = load_configs(('vacumm.cfg', ['myfile1.cfg', 'myfile2.cfg']))
merge_configs(cfgs, forprint=True, raw=True)[source]

Merge configurations

Options of the last config overrides options of the other ones, except for config file names (values then end with .ini or .cfg) that are store as a tuple.

Warning

This makes output config incompatible with getint(), etc.

print_config(section='__all__', system=True, direc=True, config=True, packages=True, extended=False, user=True, headers=True)[source]

Print current configuration

Params:
  • system: print the base of the config.
  • direc: print key directories of vacumm.
  • config: print the vacumm config.
  • packages: print the version of some important packages.
  • extended: force printing everything.

This is equivalent to (if extended=False):

>>> print get_config(section, user, asstring=True)
set_config_value(section, option, value=None, quiet=False, cfgfile=None)[source]

Create or update user configuration file

The directory of this file is given by get_user_conf_dir() and its name is vacumm.cfg. Therefore it should be: ~/.config/vacumm/vacumm.cfg.

Params:
  • section: A module or its name.
  • option: Option name.
  • value: Value of the option. If None, option is removed.
  • cfgfile, optional: Configuration file. If not provided, internal user configuration file is used (vacumm.cfg in user config directory – given by get_user_conf_dir()).
Example:
>>> set_config_value('vacumm.bathy.bathy', 'cfgfile_gridded',
    '%(mod_dir)s/bathy.gridded.cfg') # set
>>> import vacumm.bathy.bathy as B
>>> set_config_value(B, 'cfgfile_gridded') # remove
Output:

Path of the configuration file
write_default_config(cfgfile)[source]

Write the defaults config (see get_default_config()) to a file