Support functionality for extension development[source]

Returns whether a configuration item is registered under the given name


name (str) – Configuration item name

Return type:

bool, title, *, default=<class 'datalad.interface.common_cfg._NotGiven'>, default_fn=<class 'datalad.interface.common_cfg._NotGiven'>, description=None, type=<class 'datalad.interface.common_cfg._NotGiven'>, dialog=None, scope=<class 'datalad.interface.common_cfg._NotGiven'>)[source]

Register a configuration item

This function can be used by DataLad extensions and other client code to register configurations items and their documentation with DataLad’s configuration management. Specifically, these definitions will be interpreted by and acted on by the configuration command, and ConfigManager.obtain().

At minimum, each item must be given a name, and a title. Optionally, any configuration item can be given a default (or a callable to compute a default lazily on access), a type-defining/validating callable (i.e. Constraint), a (longer) description, a dialog type to enable manual entry, and a configuration scope to store entered values in.

  • name (str) – Configuration item name, in most cases starting with the prefix ‘datalad.’ followed by at least a section name, and a variable name, e.g. ‘datalad.section.variable’, following Git’s syntax for configuration items.

  • title (str) – The briefest summary of the configuration item’s purpose, typically written in the style of a headline for a dialog UI, or that of an explanatory inline comment just prior the item definitions.

  • default (optional) – A default value that is already known at the time of registering the configuration items. Can be of any type.

  • default_fn (callable, optional) – A callable to compute a default value lazily on access. The can be used, if the actual value is not yet known at the time of registering the configuration item, or if the default is expensive to compute and its evaluation needs to be deferred to prevent slow startup (configuration items are typically defined as one of the first things on import).

  • description (str, optional) – A longer description to accompany the title, possibly with instructions on how a sensible value can be determined, or with details on the impact of a configuration switch.

  • type (callable, optional) – A callable to perform arbitrary type conversion and validation of value (or default values). If validation/conversion fails, the callable must raise an arbitrary exception. The str(callable) is used as a type description.

  • dialog ({'yesno', 'question'}) – A type of UI dialog to use when manual value entry is attempted (only in interactive sessions, and only when no default is defined. title and description will be displayed in this dialog.

  • scope ({'override', 'global', 'local', 'branch'}, optional) – If particular code requests the storage of (manually entered) values, but defines no configuration scope, this default scope will be used.


ValueError – For missing required, or invalid configuration properties.