aiida.manage.configuration package#

Modules related to the configuration of an AiiDA instance.

aiida.manage.configuration._merge_deprecated_cache_yaml(config, filepath)[source]#: Merge the deprecated cache_config.yml into the config.

aiida.manage.configuration.get_config(create=False)[source]#

Return the current configuration.

If the configuration has not been loaded yet

the configuration is loaded using load_config
the global CONFIG variable is set
the configuration object is returned

Note: This function will except if no configuration file can be found. Only call this function, if you need information from the configuration file.

Parameters: create (bool) – if True, will create the configuration file if it does not already exist
Returns: the config
Return type: Config
Raises: aiida.common.ConfigurationError – if the configuration file could not be found, read or deserialized

aiida.manage.configuration.get_config_option(option_name: str) → Any[source]#

Return the value of a configuration option.

In order of priority, the option is returned from:

The current profile, if loaded and the option specified
The current configuration, if loaded and the option specified
The default value for the option

Parameters: option_name – the name of the option to return
Returns: the value of the option
Raises: aiida.common.exceptions.ConfigurationError – if the option is not found

aiida.manage.configuration.get_config_path()[source]#: Returns path to .aiida configuration directory.

aiida.manage.configuration.get_profile() → Optional[aiida.manage.configuration.profile.Profile][source]#

Return the currently loaded profile.

Returns: the globally loaded Profile instance or None

aiida.manage.configuration.load_config(create=False) → aiida.manage.configuration.config.Config[source]#

Instantiate Config object representing an AiiDA configuration file.

Warning: Contrary to get_config(), this function is uncached and will always create a new Config object. You may want to call get_config() instead.

Parameters: create (bool) – if True, will create the configuration file if it does not already exist
Returns: the config
Return type: Config
Raises: aiida.common.MissingConfigurationError – if the configuration file could not be found and create=False

aiida.manage.configuration.load_documentation_profile()[source]#

Load a dummy profile just for the purposes of being able to build the documentation.

The building of the documentation will require importing the aiida package and some code will try to access the loaded configuration and profile, which if not done will except. Calling this function allows the documentation to be built without having to install and configure AiiDA, nor having an actual database present.

aiida.manage.configuration.load_profile(profile: Optional[str] = None, allow_switch=False) → aiida.manage.configuration.profile.Profile[source]#

Load a global profile, unloading any previously loaded profile.

Note

if a profile is already loaded and no explicit profile is specified, nothing will be done

Parameters

profile – the name of the profile to load, by default will use the one marked as default in the config
allow_switch – if True, will allow switching to a different profile when storage is already loaded

Returns

the loaded Profile instance

Raises

aiida.common.exceptions.InvalidOperation – if another profile has already been loaded and allow_switch is False

aiida.manage.configuration.profile_context(profile: Optional[str] = None, allow_switch=False) → aiida.manage.configuration.profile.Profile[source]#

Return a context manager for temporarily loading a profile, and unloading on exit.

Parameters

profile – the name of the profile to load, by default will use the one marked as default in the config
allow_switch – if True, will allow switching to a different profile

Returns

a context manager for temporarily loading a profile

aiida.manage.configuration.reset_config()[source]#: Reset the globally loaded config.

Warning

This is experimental functionality and should for now be used only internally. If the reset is unclean weird unknown side-effects may occur that end up corrupting or destroying data.

Subpackages#

Submodules#

Module that defines the configuration file of an AiiDA instance and functions to create and load it.

class aiida.manage.configuration.config.Config(filepath: str, config: dict, validate: bool = True)[source]#

Bases: object

Object that represents the configuration file of an AiiDA instance.

KEY_DEFAULT_PROFILE = 'default_profile'#

KEY_OPTIONS = 'options'#

KEY_PROFILES = 'profiles'#

KEY_SCHEMA = '$schema'#

KEY_VERSION = 'CONFIG_VERSION'#

KEY_VERSION_CURRENT = 'CURRENT'#

KEY_VERSION_OLDEST_COMPATIBLE = 'OLDEST_COMPATIBLE'#

__dict__ = mappingproxy({'__module__': 'aiida.manage.configuration.config', '__doc__': 'Object that represents the configuration file of an AiiDA instance.', 'KEY_VERSION': 'CONFIG_VERSION', 'KEY_VERSION_CURRENT': 'CURRENT', 'KEY_VERSION_OLDEST_COMPATIBLE': 'OLDEST_COMPATIBLE', 'KEY_DEFAULT_PROFILE': 'default_profile', 'KEY_PROFILES': 'profiles', 'KEY_OPTIONS': 'options', 'KEY_SCHEMA': '$schema', 'from_file': <classmethod object>, '_backup': <classmethod object>, 'validate': <staticmethod object>, '__init__': <function Config.__init__>, '__eq__': <function Config.__eq__>, '__ne__': <function Config.__ne__>, 'handle_invalid': <function Config.handle_invalid>, 'dictionary': <property object>, 'version': <property object>, 'version_oldest_compatible': <property object>, 'version_settings': <property object>, 'filepath': <property object>, 'dirpath': <property object>, 'default_profile_name': <property object>, 'profile_names': <property object>, 'profiles': <property object>, 'validate_profile': <function Config.validate_profile>, 'get_profile': <function Config.get_profile>, 'add_profile': <function Config.add_profile>, 'update_profile': <function Config.update_profile>, 'remove_profile': <function Config.remove_profile>, 'delete_profile': <function Config.delete_profile>, 'set_default_profile': <function Config.set_default_profile>, 'options': <property object>, 'set_option': <function Config.set_option>, 'unset_option': <function Config.unset_option>, 'get_option': <function Config.get_option>, 'get_options': <function Config.get_options>, 'store': <function Config.store>, '_atomic_write': <function Config._atomic_write>, '__dict__': <attribute '__dict__' of 'Config' objects>, '__weakref__': <attribute '__weakref__' of 'Config' objects>, '__hash__': None, '__annotations__': {}})#

__eq__(other)[source]#: Two configurations are considered equal, when their dictionaries are equal.

__hash__ = None#

__init__(filepath: str, config: dict, validate: bool = True)[source]#

Instantiate a configuration object from a configuration dictionary and its filepath.

If an empty dictionary is passed, the constructor will create the skeleton configuration dictionary.

Parameters

filepath – the absolute filepath of the configuration file
config – the content of the configuration file in dictionary form
validate – validate the dictionary against the schema

__module__ = 'aiida.manage.configuration.config'#

__ne__(other)[source]#: Two configurations are considered unequal, when their dictionaries are unequal.

__weakref__#: list of weak references to the object (if defined)

_atomic_write(filepath=None)[source]#

Write the config as it is in memory, i.e. the contents of self.dictionary, to disk.

Note

this command will write the config from memory to a temporary file in the same directory as the target file filepath. It will then use os.rename to move the temporary file to filepath which will be overwritten if it already exists. The os.rename is the operation that gives the best guarantee of being atomic within the limitations of the application.

Parameters: filepath – optional filepath to write the contents to, if not specified, the default filename is used.

classmethod _backup(filepath)[source]#

Create a backup of the configuration file with the given filepath.

Parameters: filepath – absolute path to the configuration file to backup
Returns: the absolute path of the created backup

add_profile(profile)[source]#

Add a profile to the configuration.

Parameters: profile – the profile configuration dictionary
Returns: self

property default_profile_name#

Return the default profile name.

Returns: the default profile name or None if not defined

delete_profile(name: str, include_database: bool = True, include_database_user: bool = False, include_repository: bool = True)[source]#

Delete a profile including its storage.

Parameters

include_database – also delete the database configured for the profile.
include_database_user – also delete the database user configured for the profile.
include_repository – also delete the repository configured for the profile.

property dictionary: dict#

Return the dictionary representation of the config as it would be written to file.

Returns: dictionary representation of config as it should be written to file

property dirpath#

property filepath#

classmethod from_file(filepath)[source]#

Instantiate a configuration object from the contents of a given file.

Note

if the filepath does not exist an empty file will be created with the current default configuration and will be written to disk. If the filepath does already exist but contains a configuration with an outdated schema, the content will be migrated and then written to disk.

Parameters: filepath – the absolute path to the configuration file
Returns: Config instance

get_option(option_name, scope=None, default=True)[source]#

Get a configuration option for a certain scope.

Parameters

option_name – the name of the configuration option
scope – get the option for this profile or globally if not specified
default – boolean, If True will return the option default, even if not defined within the given scope

Returns

the option value or None if not set for the given scope

get_options(scope: Optional[str] = None) → Dict[str, Tuple[aiida.manage.configuration.options.Option, str, Any]][source]#

Return a dictionary of all option values and their source (‘profile’, ‘global’, or ‘default’).

Parameters: scope – the profile name or globally if not specified
Returns: (option, source, value)

get_profile(name: Optional[str] = None) → aiida.manage.configuration.profile.Profile[source]#

Return the profile for the given name or the default one if not specified.

Returns: the profile instance or None if it does not exist
Raises: aiida.common.ProfileConfigurationError – if the name is not found in the configuration file

handle_invalid(message)[source]#

Handle an incoming invalid configuration dictionary.

The current content of the configuration file will be written to a backup file.

Parameters: message – a string message to echo with describing the infraction

property options#

property profile_names#

Return the list of profile names.

Returns: list of profile names

property profiles#

Return the list of profiles.

Returns: the profiles
Return type: list of Profile instances

remove_profile(name)[source]#

Remove a profile from the configuration.

Parameters: name – the name of the profile to remove
Raises: aiida.common.ProfileConfigurationError – if the given profile does not exist
Returns: self

set_default_profile(name, overwrite=False)[source]#

Set the given profile as the new default.

Parameters

name – name of the profile to set as new default
overwrite – when True, set the profile as the new default even if a default profile is already defined

Raises

aiida.common.ProfileConfigurationError – if the given profile does not exist

Returns

self

set_option(option_name, option_value, scope=None, override=True)[source]#

Set a configuration option for a certain scope.

Parameters

option_name – the name of the configuration option
option_value – the option value
scope – set the option for this profile or globally if not specified
override – boolean, if False, will not override the option if it already exists

Returns

the parsed value (potentially cast to a valid type)

store()[source]#

Write the current config to file.

Note

if the configuration file already exists on disk and its contents differ from those in memory, a backup of the original file on disk will be created before overwriting it.

Returns: self

unset_option(option_name: str, scope=None)[source]#

Unset a configuration option for a certain scope.

Parameters

option_name – the name of the configuration option
scope – unset the option for this profile or globally if not specified

update_profile(profile)[source]#

Update a profile in the configuration.

Parameters: profile – the profile instance to update
Returns: self

static validate(config: dict, filepath: Optional[str] = None)[source]#: Validate a configuration dictionary.

validate_profile(name)[source]#

Validate that a profile exists.

Parameters: name – name of the profile:
Raises: aiida.common.ProfileConfigurationError – if the name is not found in the configuration file

property version#

property version_oldest_compatible#

property version_settings#

exception aiida.manage.configuration.config.ConfigValidationError(message: str, keypath: Sequence[Any] = (), schema: Optional[dict] = None, filepath: Optional[str] = None)[source]#

Bases: aiida.common.exceptions.ConfigurationError

Configuration error raised when the file contents fails validation.

__init__(message: str, keypath: Sequence[Any] = (), schema: Optional[dict] = None, filepath: Optional[str] = None)[source]#

__module__ = 'aiida.manage.configuration.config'#

__str__() → str[source]#: Return str(self).

aiida.manage.configuration.config.config_schema() → Dict[str, Any][source]#: Return the configuration schema.

Definition of known configuration options and methods to parse and get option values.

class aiida.manage.configuration.options.Option(name: str, schema: Dict[str, Any])[source]#

Bases: object

Represent a configuration option schema.

__dict__ = mappingproxy({'__module__': 'aiida.manage.configuration.options', '__doc__': 'Represent a configuration option schema.', '__init__': <function Option.__init__>, '__str__': <function Option.__str__>, 'name': <property object>, 'schema': <property object>, 'valid_type': <property object>, 'default': <property object>, 'description': <property object>, 'global_only': <property object>, 'validate': <function Option.validate>, '__dict__': <attribute '__dict__' of 'Option' objects>, '__weakref__': <attribute '__weakref__' of 'Option' objects>, '__annotations__': {}})#

__init__(name: str, schema: Dict[str, Any])[source]#

__module__ = 'aiida.manage.configuration.options'#

__str__() → str[source]#: Return str(self).

__weakref__#: list of weak references to the object (if defined)

property default: Any#

property description: str#

property global_only: bool#

property name: str#

property schema: Dict[str, Any]#

property valid_type: Any#

validate(value: Any, cast: bool = True) → Any[source]#

Validate a value

Parameters

value – The input value
cast – Attempt to cast the value to the required type

Returns

The output value

Raise

ConfigValidationError

aiida.manage.configuration.options.get_option(name: str) → aiida.manage.configuration.options.Option[source]#: Return option.

aiida.manage.configuration.options.get_option_names() → List[str][source]#: Return a list of available option names.

aiida.manage.configuration.options.get_schema_options() → Dict[str, Dict[str, Any]][source]#: Return schema for options.

aiida.manage.configuration.options.parse_option(option_name: str, option_value: Any) → Tuple[aiida.manage.configuration.options.Option, Any][source]#

Parse and validate a value for a configuration option.

Parameters

option_name – the name of the configuration option
option_value – the option value

Returns

a tuple of the option and the parsed value

AiiDA profile related code

class aiida.manage.configuration.profile.Profile(name: str, config: Mapping[str, Any], validate=True)[source]#

Bases: object

Class that models a profile as it is stored in the configuration file of an AiiDA instance.

KEY_DEFAULT_USER_EMAIL = 'default_user_email'#

KEY_OPTIONS = 'options'#

KEY_PROCESS = 'process_control'#

KEY_PROCESS_BACKEND = 'backend'#

KEY_PROCESS_CONFIG = 'config'#

KEY_STORAGE = 'storage'#

KEY_STORAGE_BACKEND = 'backend'#

KEY_STORAGE_CONFIG = 'config'#

KEY_TEST_PROFILE = 'test_profile'#

KEY_UUID = 'PROFILE_UUID'#

REQUIRED_KEYS = ('storage', 'process_control')#

__dict__ = mappingproxy({'__module__': 'aiida.manage.configuration.profile', '__doc__': 'Class that models a profile as it is stored in the configuration file of an AiiDA instance.', 'KEY_UUID': 'PROFILE_UUID', 'KEY_DEFAULT_USER_EMAIL': 'default_user_email', 'KEY_STORAGE': 'storage', 'KEY_PROCESS': 'process_control', 'KEY_STORAGE_BACKEND': 'backend', 'KEY_STORAGE_CONFIG': 'config', 'KEY_PROCESS_BACKEND': 'backend', 'KEY_PROCESS_CONFIG': 'config', 'KEY_OPTIONS': 'options', 'KEY_TEST_PROFILE': 'test_profile', 'REQUIRED_KEYS': ('storage', 'process_control'), '__init__': <function Profile.__init__>, '__repr__': <function Profile.__repr__>, 'copy': <function Profile.copy>, 'uuid': <property object>, 'default_user_email': <property object>, 'storage_backend': <property object>, 'storage_config': <property object>, 'set_storage': <function Profile.set_storage>, 'storage_cls': <property object>, 'process_control_backend': <property object>, 'process_control_config': <property object>, 'set_process_controller': <function Profile.set_process_controller>, 'options': <property object>, 'get_option': <function Profile.get_option>, 'set_option': <function Profile.set_option>, 'unset_option': <function Profile.unset_option>, 'name': <property object>, 'dictionary': <property object>, 'is_test_profile': <property object>, 'repository_path': <property object>, 'rmq_prefix': <property object>, 'get_rmq_url': <function Profile.get_rmq_url>, 'filepaths': <property object>, '__dict__': <attribute '__dict__' of 'Profile' objects>, '__weakref__': <attribute '__weakref__' of 'Profile' objects>, '__annotations__': {'_attributes': 'Dict[str, Any]'}})#

__init__(name: str, config: Mapping[str, Any], validate=True)[source]#: Load a profile with the profile configuration.

__module__ = 'aiida.manage.configuration.profile'#

__repr__() → str[source]#: Return repr(self).

__weakref__#: list of weak references to the object (if defined)

copy()[source]#: Return a copy of the profile.

property default_user_email: Optional[str]#: Return the default user email.

property dictionary: Dict[str, Any]#

Return the profile attributes as a dictionary with keys as it is stored in the config

Returns: the profile configuration dictionary

property filepaths#

Return the filepaths used by this profile.

Returns: a dictionary of filepaths

get_option(option_key, default=None)[source]#

get_rmq_url() → str[source]#: Return the RMQ url for this profile.

property is_test_profile: bool#

Return whether the profile is a test profile

Returns: boolean, True if test profile, False otherwise

property name#

Return the profile name.

Returns: the profile name

property options#

property process_control_backend: str#: Return the type of the process control backend.

property process_control_config: Dict[str, Any]#: Return the configuration required by the process control backend.

property repository_path: pathlib.Path#

Return the absolute path of the repository configured for this profile.

The URI should be in the format protocol://address

Note: At the moment, only the file protocol is supported.
Returns: absolute filepath of the profile’s file repository

property rmq_prefix: str#

Return the prefix that should be used for RMQ resources

Returns: the rmq prefix string

set_option(option_key, value, override=True)[source]#

Set a configuration option for a certain scope.

Parameters

option_key – the key of the configuration option
option_value – the option value
override – boolean, if False, will not override the option if it already exists

set_process_controller(name: str, config: Dict[str, Any]) → None[source]#

Set the process control backend and its configuration.

Parameters

name – the name of the process backend
config – the configuration of the process backend

set_storage(name: str, config: Dict[str, Any]) → None[source]#

Set the storage backend and its configuration.

Parameters

name – the name of the storage backend
config – the configuration of the storage backend

property storage_backend: str#: Return the type of the storage backend.

property storage_cls: Type[StorageBackend]#: Return the storage backend class for this profile.

property storage_config: Dict[str, Any]#: Return the configuration required by the storage backend.

unset_option(option_key)[source]#

property uuid: str#

Return the profile uuid.

Returns: string UUID

Base settings required for the configuration of an AiiDA instance.

aiida.manage.configuration.settings.create_instance_directories()[source]#

Create the base directories required for a new AiiDA instance.

This will create the base AiiDA directory defined by the AIIDA_CONFIG_FOLDER variable, unless it already exists. Subsequently, it will create the daemon directory within it and the daemon log directory.

aiida.manage.configuration.settings.set_configuration_directory()[source]#

Determine the location of the configuration directory and set the related global variables.

The location of the configuration folder will be determined and optionally created following these heuristics:

If the AIIDA_PATH variable is set, all the paths will be checked to see if they contain a configuration folder. The first one to be encountered will be set as AIIDA_CONFIG_FOLDER. If none of them contain one, a configuration folder will be created in the last path considered.

If the AIIDA_PATH variable is not set the DEFAULT_AIIDA_PATH value will be used as base path and if it does not yet contain a configuration folder, one will be created.

In principle then, a configuration folder should always be found or automatically created.

aiida.manage package

aiida.manage.configuration.migrations package