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
- 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 callget_config()
instead.- Parameters
create (bool) – if True, will create the configuration file if it does not already exist
- Returns
the config
- Return type
- 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__': {}})#
- __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 useos.rename
to move the temporary file tofilepath
which will be overwritten if it already exists. Theos.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'#
- 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__': {}})#
- __module__ = 'aiida.manage.configuration.options'#
- __weakref__#
list of weak references to the object (if defined)
- property default: Any#
- property valid_type: Any#
- 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'#
- __weakref__#
list of weak references to the object (if defined)
- 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
- 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_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_cls: Type[StorageBackend]#
Return the storage backend class for this profile.
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(aiida_config_folder: Optional[pathlib.Path] = None)[source]#
Determine location of configuration directory, set related global variables and create instance directories.
The location of the configuration folder will be determined and optionally created following these heuristics:
If an explicit path is provided by aiida_config_folder, that will be set as the configuration folder.
Otherwise, 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.