from __future__ import annotations
import copy
import json
import logging
import os
from collections.abc import Mapping
from importlib.resources import files
from os.path import expanduser
from pathlib import Path
from typing import Any
import jsonschema
logger = logging.getLogger(__name__)
EMPTY_USER_SCHEMA = "User schema at {} not found. User settings won't be validated"
MISS_DESC = """ Passing a description without a type does not make sense.
Description is ignored """
BASE_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "schema for a user qcodes config file",
"properties": {},
"required": []
}
# https://github.com/python/mypy/issues/4182
_PARENT_MODULE = ".".join(__loader__.name.split(".")[:-1]) # type: ignore[name-defined]
[docs]
class Config:
"""
QCoDeS config system
Start with sane defaults, which you can't change, and
then customize your experience using files that update the configuration.
"""
config_file_name = "qcodesrc.json"
"""Name of config file"""
schema_file_name = "qcodesrc_schema.json"
"""Name of schema file"""
# get abs path of packge config file
default_file_name = str(files(_PARENT_MODULE) / config_file_name)
"""Filename of default config"""
current_config_path = default_file_name
"""Path of the last loaded config file"""
# get abs path of schema file
schema_default_file_name = str(files(_PARENT_MODULE) / schema_file_name)
"""Filename of default schema"""
# home dir, os independent
home_file_name = expanduser(os.path.join("~", config_file_name))
"""Filename of home config"""
schema_home_file_name = home_file_name.replace(config_file_name,
schema_file_name)
"""Filename of home schema"""
# this is for *nix people
env_file_name = os.environ.get("QCODES_CONFIG", "")
"""Filename of env config"""
schema_env_file_name = env_file_name.replace(config_file_name,
schema_file_name)
"""Filename of env schema"""
# current working dir
cwd_file_name = os.path.join(Path.cwd(), config_file_name)
"""Filename of cwd config"""
schema_cwd_file_name = cwd_file_name.replace(config_file_name,
schema_file_name)
"""Filename of cwd schema"""
current_schema: DotDict | None = None
"""Validators and descriptions of config values"""
current_config: DotDict | None = None
"""Valid config values"""
defaults: DotDict
"""The default configuration"""
defaults_schema: DotDict
"""The default schema"""
def __init__(self, path: str | None = None) -> None:
"""
Args:
path: Optional path to directory containing
a `qcodesrc.json` config file
"""
self._loaded_config_files = [self.default_file_name]
self._diff_config: dict[str, Any] = {}
self._diff_schema: dict[str, Any] = {}
self.config_file_path = path
self.defaults, self.defaults_schema = self.load_default()
self.update_config()
[docs]
def load_default(self) -> tuple[DotDict, DotDict]:
defaults = self.load_config(self.default_file_name)
defaults_schema = self.load_config(self.schema_default_file_name)
self.validate(defaults, defaults_schema)
return defaults, defaults_schema
[docs]
def update_config(self, path: str | None = None) -> dict[str, Any]:
"""
Load defaults updates with cwd, env, home and the path specified
and validates.
A configuration file must be called qcodesrc.json
A schema file must be called qcodesrc_schema.json
Configuration files (and their schema) are loaded and updated from the
directories in the following order:
- default json config file from the repository
- user json config in user home directory
- user json config in $QCODES_CONFIG
- user json config in current working directory
- user json file in the path specified
If a key/value is not specified in the user configuration the default
is used. Key/value pairs loaded later will take preference over those
loaded earlier.
Configs are validated after every update.
Validation is also performed against a user provided schema if it's
found in the directory.
Args:
path: Optional path to directory containing a `qcodesrc.json`
config file
"""
config = copy.deepcopy(self.defaults)
self.current_schema = copy.deepcopy(self.defaults_schema)
self._loaded_config_files = [self.default_file_name]
self._update_config_from_file(self.home_file_name,
self.schema_home_file_name,
config)
self._update_config_from_file(self.env_file_name,
self.schema_env_file_name,
config)
self._update_config_from_file(self.cwd_file_name,
self.schema_cwd_file_name,
config)
if path is not None:
self.config_file_path = path
if self.config_file_path is not None:
config_file = os.path.join(self.config_file_path,
self.config_file_name)
schema_file = os.path.join(self.config_file_path,
self.schema_file_name)
self._update_config_from_file(config_file, schema_file, config)
if config is None:
raise RuntimeError("Could not load config from any of the "
"expected locations.")
self.current_config = config
self.current_config_path = self._loaded_config_files[-1]
return config
def _update_config_from_file(
self, file_path: str, schema: str, config: dict[str, Any]
) -> None:
"""
Updated ``config`` dictionary with config information from file in
``file_path`` that has schema specified in ``schema``
Args:
file_path: Path to `qcodesrc.json` config file
schema: Path to `qcodesrc_schema.json` to be used
config: Config dictionary to be updated.
"""
if os.path.isfile(file_path):
self._loaded_config_files.append(file_path)
my_config = self.load_config(file_path)
config = update(config, my_config)
self.validate(config, self.current_schema, schema)
[docs]
def validate(
self,
json_config: Mapping[str, Any] | None = None,
schema: Mapping[str, Any] | None = None,
extra_schema_path: str | None = None,
) -> None:
"""
Validate configuration; if no arguments are passed, the default
config is validated against the default schema. If either
``json_config`` or ``schema`` is passed the corresponding
default is not used.
Args:
json_config: json dictionary to validate
schema: schema dictionary
extra_schema_path: schema path that contains extra validators to be
added to schema dictionary
"""
if schema is None:
if self.current_schema is None:
raise RuntimeError("Cannot validate as current_schema is None")
schema = self.current_schema
if json_config is None:
json_config = self.current_config
if extra_schema_path is not None:
# add custom validation
if os.path.isfile(extra_schema_path):
with open(extra_schema_path) as f:
# user schema has to be both valid in itself
# but then just update the user properties
# so that default types and values can NEVER
# be overwritten
new_user = json.load(f)["properties"]["user"]
user = schema["properties"]['user']
user["properties"].update(new_user["properties"])
else:
logger.warning(EMPTY_USER_SCHEMA.format(extra_schema_path))
jsonschema.validate(json_config, schema)
[docs]
def add(
self,
key: str,
value: Any,
value_type: str | None = None,
description: str | None = None,
default: Any | None = None,
) -> None:
"""Add custom config value in place
Adds ``key``, ``value`` with optional ``value_type`` to user config and
schema. If ``value_type`` is specified then the new value is validated.
Args:
key: key to be added under user config
value: value to add to config
value_type: type of value, allowed are string, boolean, integer
description: description of key to add to schema
default: default value, stored only in the schema
Examples:
>>> defaults.add("trace_color", "blue", "string", "description")
will update the config:
::
...
"user": { "trace_color": "blue"}
...
and the schema:
::
...
"user":{
"type" : "object",
"description": "controls user settings of qcodes"
"properties" : {
"trace_color": {
"description" : "description",
"type": "string"
}
}
}
...
Todo:
- Add enum support for value_type
- finish _diffing
"""
if self.current_config is None:
raise RuntimeError("Cannot add value to empty config")
self.current_config["user"].update({key: value})
if self._diff_config.get("user", True):
self._diff_config["user"] = {}
self._diff_config["user"].update({key: value})
if value_type is None:
if description is not None:
logger.warning(MISS_DESC)
else:
# update schema!
schema_entry: dict[str, dict[str, str | Any]]
schema_entry = {key: {"type": value_type}}
if description is not None:
schema_entry = {
key: {
"type": value_type,
"default": default,
"description": description
}
}
# the schema is nested we only update properties of the user object
if self.current_schema is None:
raise RuntimeError("Cannot add value as no current schema is "
"set")
user = self.current_schema['properties']["user"]
user["properties"].update(schema_entry)
self.validate(self.current_config, self.current_schema)
# TODO(giulioungaretti) finish diffing
# now we update the entire schema
# and the entire configuration
# if it's saved then it will always
# take precedence even if the defaults
# values are changed upstream, and the local
# ones were actually left to their default
# values
if not self._diff_schema:
self._diff_schema = BASE_SCHEMA
props = self._diff_schema['properties']
if props.get("user", True):
props["user"] = {}
props["user"].update(schema_entry)
[docs]
@staticmethod
def load_config(path: str) -> DotDict:
"""Load a config JSON file
Args:
path: path to the config file
Return:
a dot accessible dictionary config object
Raises:
FileNotFoundError: if config is missing
"""
with open(path) as fp:
config = json.load(fp)
logger.debug(f'Loading config from {path}')
config_dot_dict = DotDict(config)
return config_dot_dict
[docs]
def save_config(self, path: str) -> None:
"""
Save current config to file at given path.
Args:
path: path of new file
"""
with open(path, "w") as fp:
json.dump(self.current_config, fp, indent=4)
[docs]
def save_schema(self, path: str) -> None:
"""
Save current schema to file at given path.
Args:
path: path of new file
"""
with open(path, "w") as fp:
json.dump(self.current_schema, fp, indent=4)
[docs]
def save_to_home(self) -> None:
"""Save config and schema to files in home dir"""
self.save_config(self.home_file_name)
self.save_schema(self.schema_home_file_name)
[docs]
def save_to_env(self) -> None:
"""Save config and schema to files in path specified in env variable"""
self.save_config(self.env_file_name)
self.save_schema(self.schema_env_file_name)
[docs]
def save_to_cwd(self) -> None:
"""Save config and schema to files in current working dir"""
self.save_config(self.cwd_file_name)
self.save_schema(self.schema_cwd_file_name)
[docs]
def describe(self, name: str) -> str:
"""
Describe a configuration entry
Args:
name: name of entry to describe in 'dotdict' notation,
e.g. name="user.scriptfolder"
"""
val = self.current_config
if val is None:
raise RuntimeError("Config is empty, cannot describe entry.")
if self.current_schema is None:
raise RuntimeError("No schema found, cannot describe entry.")
sch = self.current_schema["properties"]
for key in name.split('.'):
if val is None:
raise RuntimeError(f"Cannot describe {name} Some part of it "
f"is null")
val = val[key]
if sch.get(key):
sch = sch[key]
else:
sch = sch['properties'][key]
description = sch.get("description", None) or "Generic value"
_type = str(sch.get("type", None)) or "Not defined"
default = sch.get("default", None) or "Not defined"
# add cool description to docstring
base_docstring = """{}.\nCurrent value: {}. Type: {}. Default: {}."""
doc = base_docstring.format(description, val, _type, default)
return doc
def __getitem__(self, name: str) -> Any:
val = self.current_config
for key in name.split('.'):
if val is None:
raise KeyError(f"{name} not found in current config")
val = val[key]
return val
def __getattr__(self, name: str) -> Any:
return getattr(self.current_config, name)
def __repr__(self) -> str:
old = super().__repr__()
output = (f"Current values: \n {self.current_config} \n"
f"Current paths: \n {self._loaded_config_files} \n"
f"{old}")
return output
[docs]
class DotDict(dict[str, Any]):
"""
Wrapper dict that allows to get dotted attributes
Requires keys to be strings.
"""
def __init__(self, value: Mapping[str, Any] | None = None):
if value is None:
pass
else:
for key in value:
self.__setitem__(key, value[key])
def __setitem__(self, key: str, value: Any) -> None:
if '.' in key:
myKey, restOfKey = key.split('.', 1)
target = self.setdefault(myKey, DotDict())
target[restOfKey] = value
else:
if isinstance(value, dict) and not isinstance(value, DotDict):
value = DotDict(value)
dict.__setitem__(self, key, value)
def __getitem__(self, key: str) -> Any:
if '.' not in key:
return dict.__getitem__(self, key)
myKey, restOfKey = key.split('.', 1)
target = dict.__getitem__(self, myKey)
return target[restOfKey]
def __contains__(self, key: object) -> bool:
if not isinstance(key, str):
return False
if '.' not in key:
return super().__contains__(key)
myKey, restOfKey = key.split('.', 1)
target = dict.__getitem__(self, myKey)
return restOfKey in target
def __deepcopy__(self, memo: dict[Any, Any] | None) -> DotDict:
return DotDict(copy.deepcopy(dict(self)))
[docs]
def __getattr__(self, name: str) -> Any:
"""
Overwrite ``__getattr__`` to provide dot access
"""
return self.__getitem__(name)
[docs]
def __setattr__(self, key: str, value: Any) -> None:
"""
Overwrite ``__setattr__`` to provide dot access
"""
self.__setitem__(key, value)
def update(d: dict[Any, Any], u: Mapping[Any, Any]) -> dict[Any, Any]:
for k, v in u.items():
if isinstance(v, Mapping):
r = update(d.get(k, {}), v)
d[k] = r
else:
d[k] = u[k]
return d