datalad.config

class datalad.config.ConfigManager(dataset=None, dataset_only=False, overrides=None)[source]

Bases: object

Thin wrapper around git-config with support for a dataset configuration.

The general idea is to have an object that is primarily used to read/query configuration option. Upon creation, current configuration is read via one (or max two, in the case of the presence of dataset-specific configuration) calls to git config. If this class is initialized with a Dataset instance, it supports reading and writing configuration from .datalad/config inside a dataset too. This file is committed to Git and hence useful to ship certain configuration items with a dataset.

The API aims to provide the most significant read-access API of a dictionary, the Python ConfigParser, and GitPython’s config parser implementations.

This class is presently not capable of efficiently writing multiple configurations items at once. Instead, each modification results in a dedicated call to git config. This author thinks this is OK, as he cannot think of a situation where a large number of items need to be written during normal operation. If such need arises, various solutions are possible (via GitPython, or an independent writer).

Each instance carries a public overrides attribute. This dictionary contains variables that override any setting read from a file. The overrides are persistent across reloads, and are not modified by any of the manipulation methods, such as set or unset.

Any DATALAD_* environment variable is also presented as a configuration item. Settings read from environment variables are not stored in any of the configuration file, but are read dynamically from the environment at each reload() call. Their values take precedence over any specification in configuration files, and even overrides.

Parameters:
  • dataset (Dataset, optional) – If provided, all git config calls are executed in this dataset’s directory. Moreover, any modifications are, by default, directed to this dataset’s configuration file (which will be created on demand)
  • dataset_only (bool) – If True, configuration items are only read from a datasets persistent configuration file, if any present (the one in .datalad/config, not .git/config).
  • overrides (dict, optional) – Variable overrides, see general class documentation for details.
add(var, value, where='dataset', reload=True)[source]

Add a configuration variable and value

Parameters:
  • var (str) – Variable name including any section like git config expects them, e.g. ‘core.editor’
  • value (str) – Variable value
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
get(k[, d]) → D[k] if k in D, else d. d defaults to None.[source]
get_value(section, option, default=None)[source]

Like get(), but with an optional default value

If the default is not None, the given default value will be returned in case the option did not exist. This behavior imitates GitPython’s config parser.

getbool(section, option, default=None)[source]

A convenience method which coerces the option value to a bool

Values “on”, “yes”, “true” and any int!=0 are considered True Values which evaluate to bool False, “off”, “no”, “false” are considered False TypeError is raised for other values.

getfloat(section, option)[source]

A convenience method which coerces the option value to a float

getint(section, option)[source]

A convenience method which coerces the option value to an integer

has_option(section, option)[source]

If the given section exists, and contains the given option

has_section(section)[source]

Indicates whether a section is present in the configuration

items(section=None)[source]

Return a list of (name, value) pairs for each option

Optionally limited to a given section.

keys()[source]

Returns list of configuration item names

obtain(var, default=None, dialog_type=None, valtype=None, store=False, where=None, reload=True, **kwargs)[source]

Convenience method to obtain settings interactively, if needed

A UI will be used to ask for user input in interactive sessions. Questions to ask, and additional explanations can be passed directly as arguments, or retrieved from a list of pre-configured items.

Additionally, this method allows for type conversion and storage of obtained settings. Both aspects can also be pre-configured.

Parameters:
  • var (str) – Variable name including any section like git config expects them, e.g. ‘core.editor’
  • default (any type) – In interactive sessions and if store is True, this default value will be presented to the user for confirmation (or modification). In all other cases, this value will be silently assigned unless there is an existing configuration setting.
  • dialog_type ({'question', 'yesno', None}) – Which dialog type to use in interactive sessions. If None, pre-configured UI options are used.
  • store (bool) – Whether to store the obtained value (or default)
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
  • **kwargs – Additional arguments for the UI function call, such as a question text.
options(section)[source]

Returns a list of options available in the specified section.

reload(force=False)[source]

Reload all configuration items from the configured sources

If force is False, all files configuration was previously read from are checked for differences in the modification times. If no difference is found for any file no reload is performed. This mechanism will not detect newly created global configuration files, use force in this case.

remove_section(sec, where='dataset', reload=True)[source]

Rename a configuration section

Parameters:
  • sec (str) – Name of the section to remove.
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
rename_section(old, new, where='dataset', reload=True)[source]

Rename a configuration section

Parameters:
  • old (str) – Name of the section to rename.
  • new (str) – Name of the section to rename to.
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
sections()[source]

Returns a list of the sections available

set(var, value, where='dataset', reload=True, force=False)[source]

Set a variable to a value.

In opposition to add, this replaces the value of var if there is one already.

Parameters:
  • var (str) – Variable name including any section like git config expects them, e.g. ‘core.editor’
  • value (str) – Variable value
  • force (bool) – if set, replaces all occurrences of var by a single one with the given value. Otherwise raise if multiple entries for var exist already
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
unset(var, where='dataset', reload=True)[source]

Remove all occurrences of a variable

Parameters:
  • var (str) – Name of the variable to remove
  • where ({'dataset', 'local', 'global'}, optional) – Indicator which configuration file to modify. ‘dataset’ indicates the persistent configuration in .datalad/config of a dataset; ‘local’ the configuration of a dataset’s Git repository in .git/config; ‘global’ refers to the general configuration that is not specific to a single repository (usually in $USER/.gitconfig).
  • reload (bool) – Flag whether to reload the configuration from file(s) after modification. This can be disable to make multiple sequential modifications slightly more efficient.
datalad.config.anything2bool(val)[source]
datalad.config.get_git_version(runner)[source]

Return version of available git