CHANfiG aims to make your configuration easier.
There are tons of configurable parameters in training a Machine Learning model. To configure all these parameters, researchers usually need to write gigantic config files, sometimes even thousands of lines. Most of the configs are just replicates of the default arguments of certain functions, resulting in many unnecessary declarations. It is also very hard to alter the configurations. One needs to navigate and open the right configuration file, make changes, save and exit. These had wasted an uncountable1 amount of precious time and are no doubt a crime. Using argparse could relieve the burdens to some extent. However, it takes a lot of work to make it compatible with existing config files, and its lack of nesting limits its potential.
CHANfiG would like to make a change.
You just type the alternations in the command line, and leave everything else to CHANfiG.
CHANfiG is highly inspired by YACS. Different from the paradigm of YACS( your code + a YACS config for experiment E (+ external dependencies + hardware + other nuisance terms ...) = reproducible experiment E), The paradigm of CHANfiG is:
your code + command line arguments (+ optional CHANfiG config + external dependencies + hardware + other nuisance terms ...) = reproducible experiment E (+ optional CHANfiG config for experiment E)
A Config is basically a nested dict structure.
However, the default Python dict is hard to manipulate.
The only way to access a dict member is through dict['name'], which is obviously extremely complex. Even worse, if the dict is nested like a config, member access could be something like dict['parent']['children']['name'].
Enough is enough, it is time to make a change.
We need attribute-style access, and we need it now. dict.name and dict.parent.children.name is all you need.
Although there have been some other works that achieve a similar functionality of attribute-style access to dict members. Their Config object either uses a separate dict to store information from attribute-style access (EasyDict), which may lead to inconsistency between attribute-style access and dict-style access; or re-use the existing __dict__ and redirect dict-style access (ml_collections), which may result in confliction between attributes and members of Config.
To overcome the aforementioned limitations, we inherit the Python built-in dict to create FlatDict, DefaultDict, NestedDict, Config, and Registry. We also introduce Variable to allow sharing a value across multiple places, and ConfigParser to parse command line arguments.
FlatDict improves the default dict in 3 aspects.
FlatDict incorporates a merge method that allows you to merge a Mapping, an Iterable, or a path to the FlatDict. Different from built-in update, merge assign values instead of replace, which makes it works better with DefaultDict.
dict in Python is ordered since Python 3.7, but there isn\u2019t a built-in method to help you sort a dict. FlatDictsupportssort to help you manage your dict.
Moreover, FlatDict comes with difference and intersect, which makes it very easy to compare a FlatDict with other Mapping, Iterable, or a path.
FlatDict supports to method similar to PyTorch Tensors. You can simply convert all member values of FlatDict to a certain type or pass to a device in the same way.
FlatDict also integrates cpu, gpu (cuda), and tpu (xla) methods for easier access.
FlatDict provides json, jsons, yaml and yamls methods to dump FlatDict to a file or string. It also provides from_json, from_jsons, from_yaml and from_yamls methods to build a FlatDict from a string or file.
FlatDict also includes dump and load methods which determines the type by its extension and dump/load FlatDict to/from a file.
To facility the needs of default values, we incorporate DefaultDict which accepts default_factory and works just like a collections.defaultdict.
Since most Configs are in a nested structure, we further propose a NestedDict.
Based on DefaultDict, NestedDict provides all_keys, all_values, and all_items methods to allow iterating over the whole nested structure at once.
NestedDict also comes with apply and apply_ methods, which made it easier to manipulate the nested structure.
Config extends the functionality by supporting freeze and defrost, and by adding a built-in ConfigParser to pare command line arguments.
Note that Config also has default_factory=Config() by default for convenience.
Registry extends the NestedDict and supports register, lookup, and build to help you register constructors and build objects from a Config.
Have one value for multiple names at multiple places? We got you covered.
Just wrap the value with Variable, and one alteration will be reflected everywhere.
Variable also supports type, choices, validator, and required to ensure the correctness of the value.
To make it even easier, Variable also supports help to provide a description when using ConfigParser.
ConfigParser extends ArgumentParser and provides parse and parse_config to parse command line arguments.
CHANfiG has great backward compatibility with previous configs.
No matter if your old config is json or yaml, you could directly read from them.
And if you are using yacs, just replace CfgNode with Config and enjoy all the additional benefits that CHANfiG provides.
Moreover, if you find a name in the config is too long for command-line, you could simply call self.add_argument with proper dest to use a shorter name in command-line, as you do with argparse.
from chanfig import Config, Variable\nclass Model:\ndef __init__(self, encoder, dropout=0.1, activation='ReLU'):\nself.encoder = Encoder(**encoder)\nself.dropout = Dropout(dropout)\nself.activation = getattr(Activation, activation)\ndef main(config):\nmodel = Model(**config.model)\noptimizer = Optimizer(**config.optimizer)\nscheduler = Scheduler(**config.scheduler)\ndataset = Dataset(**config.dataset)\ndataloader = Dataloader(**config.dataloader)\nclass TestConfig(Config):\ndef __init__(self):\nsuper().__init__()\ndropout = Variable(0.1)\nself.name = \"CHANfiG\"\nself.seed = 1013\nself.data.batch_size = 64\nself.model.encoder.num_layers = 6\nself.model.decoder.num_layers = 6\nself.model.dropout = dropout\nself.model.encoder.dropout = dropout\nself.model.decoder.dropout = dropout\nself.activation = \"GELU\"\nself.optim.lr = 1e-3\nself.add_argument(\"--batch_size\", dest=\"data.batch_size\")\nself.add_argument(\"--lr\", dest=\"optim.lr\")\ndef post(self):\nself.id = f\"{self.name}_{self.seed}\"\nif __name__ == '__main__':\n# config = Config.load('config.yaml') # in case you want to read from a yaml\n# config = Config.load('config.json') # in case you want to read from a json\n# existing_configs = {'data.batch_size': 64, 'model.encoder.num_layers': 8}\n# config = Config(**existing_configs) # in case you have some config in dict to load\nconfig = TestConfig()\nconfig = config.parse()\n# config.merge('dataset.yaml') # in case you want to merge a yaml\n# config.merge('dataset.json') # in case you want to merge a json\n# note that the value of merge will override current values\nconfig.model.decoder.num_layers = 8\nconfig.freeze()\nprint(config)\n# main(config)\n# config.yaml('config.yaml') # in case you want to save a yaml\n# config.json('config.json') # in case you want to save a json\nAll you need to do is just run a line:
Bashpython main.py --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\nYou could also load a default configure file and make changes based on it:
Note, you must specify config.parse(default_config='config') to correctly load the default config.
python main.py --config meow.yaml --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\nIf you have made it dump current configurations, this should be in the written file:
YAMLactivation: GELU\ndata:\nbatch_size: 64\nid: CHANfiG_1013\nmodel:\ndecoder:\ndropout: 0.1\nnum_layers: 6\ndropout: 0.1\nencoder:\ndropout: 0.1\nnum_layers: 6\nname: CHANfiG\noptim:\nlr: 0.005\nseed: 1013\n{\n\"name\": \"CHANfiG\",\n\"seed\": 1013,\n\"data\": {\n\"batch_size\": 64\n},\n\"model\": {\n\"encoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"decoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"dropout\": 0.1\n},\n\"activation\": \"GELU\",\n\"optim\": {\n\"lr\": 0.005\n},\n\"id\": \"CHANfiG_1013\"\n}\nDefine the default arguments in function, put alterations in CLI, and leave the rest to CHANfiG.
"},{"location":"#installation","title":"Installation","text":"Install the most recent stable version on pypi:
Bashpip install chanfig\nInstall the latest version from source:
Bashpip install git+https://github.com/ZhiyuanChen/CHANfiG\nIt works the way it should have worked.
"},{"location":"#license","title":"License","text":"CHANfiG is multi-licensed under the following licenses:
You can choose any (one or more) of these licenses if you use this work.
SPDX-License-Identifier: Unlicense OR AGPL-3.0-or-later OR GPL-2.0-or-later OR BSD-4-Clause OR MIT OR Apache-2.0
fun fact: time is always uncountable.\u00a0\u21a9
Config","text":" Bases: NestedDict
Config is an extension of NestedDict.
The differences between Config and NestedDict lies in 3 aspects:
Config has default_factory set to Config and convert_mapping set to True by default.Config has a frozen attribute, which can be toggled with freeze(lock) & defrost(unlock) or temporarily changed with locked & unlocked.Config has a ConfigParser built-in, and supports add_argument and parse.Config also features a post method and a boot method to support lazy-initilisation. This is useful when you want to perform some post-processing on the config. For example, some values may be a combination of other values, and you may define them in post.
boot is introduced to call all post methods in the nested structure of Config object. By default, boot will be called to after Config is parsed.
You could also manually call boot if you you don\u2019t parse command-line arguments.
Since Config has default_factory set to Config, accessing anything that does not exist will create a new empty Config sub-attribute.
A frozen Config does not have this behaviour and will raises KeyError when accessing anything that does not exist.
It is recommended to call config.freeze() or config.to(NestedDict) to avoid this behaviour.
Attributes:
Name Type Descriptionparser ConfigParser Parser for command-line arguments.
frozen bool If True, the config is frozen and cannot be altered.
Examples:
Python Console Session>>> c = Config(**{\"f.n\": \"chang\"})\n>>> c.i.d = 1013\n>>> c.i.d\n1013\n>>> c.d.i\nConfig(<class 'chanfig.config.Config'>, )\n>>> c.freeze().dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}, 'd': {'i': {}}}\n>>> c.d.i = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.d.e\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'e'\n>>> with c.unlocked():\n... del c.d\n>>> c.dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}}\nchanfig/config.py Pythonclass Config(NestedDict): # type: ignore\nr\"\"\"\n `Config` is an extension of `NestedDict`.\n The differences between `Config` and `NestedDict` lies in 3 aspects:\n 1. `Config` has `default_factory` set to `Config` and `convert_mapping` set to `True` by default.\n 2. `Config` has a `frozen` attribute, which can be toggled with `freeze`(`lock`) & `defrost`(`unlock`)\n or temporarily changed with `locked` & `unlocked`.\n 3. `Config` has a `ConfigParser` built-in, and supports `add_argument` and `parse`.\n Config also features a `post` method and a `boot` method to support lazy-initilisation.\n This is useful when you want to perform some post-processing on the config.\n For example, some values may be a combination of other values, and you may define them in `post`.\n `boot` is introduced to call all `post` methods in the nested structure of `Config` object.\n By default, `boot` will be called to after `Config` is parsed.\n You could also manually call `boot` if you you don't parse command-line arguments.\n Notes:\n Since `Config` has `default_factory` set to `Config`,\n accessing anything that does not exist will create a new empty Config sub-attribute.\n A **frozen** `Config` does not have this behaviour and\n will raises `KeyError` when accessing anything that does not exist.\n It is recommended to call `config.freeze()` or `config.to(NestedDict)` to avoid this behaviour.\n Attributes:\n parser (ConfigParser): Parser for command-line arguments.\n frozen (bool): If `True`, the config is frozen and cannot be altered.\n Examples:\n >>> c = Config(**{\"f.n\": \"chang\"})\n >>> c.i.d = 1013\n >>> c.i.d\n 1013\n >>> c.d.i\n Config(<class 'chanfig.config.Config'>, )\n >>> c.freeze().dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}, 'd': {'i': {}}}\n >>> c.d.i = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.d.e\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'e'\n >>> with c.unlocked():\n ... del c.d\n >>> c.dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}}\n \"\"\"\nparser: None # ConfigParser, Python 3.7 does not support forward reference\nfrozen: bool = False\ndef __init__(self, *args: Any, default_factory: Callable | None = None, **kwargs: Any):\nif default_factory is None:\ndefault_factory = Config\nsuper().__init__(*args, default_factory=default_factory, **kwargs)\ndef post(self) -> Config | None:\nr\"\"\"\n Post process of `Config`.\n Some `Config` may need to do some post process after `Config` is initialised.\n `post` is provided for this lazy-initialisation purpose.\n By default, `post` calls `interpolate` to perform variable interpolation.\n Note that you should always call `boot` to apply `post` rather than calling `post` directly,\n as `boot` recursively call `post` on sub-configs.\n See Also: [`boot`][chanfig.Config.boot]\n Returns:\n self:\n Examples:\n >>> class PostConfig(Config):\n ... def post(self):\n ... if isinstance(self.data, str):\n ... self.data = Config(feature=self.data, label=self.data)\n ... return self\n >>> c = PostConfig(data=\"path\")\n >>> c.post()\n PostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n \"\"\"\nself.interpolate()\nself.validate()\nreturn self\ndef boot(self) -> Config:\nr\"\"\"\n Apply `post` recursively.\n Sub-config may have their own `post` method.\n `boot` is provided to apply `post` recursively.\n By default, `boot` is called after `Config` is parsed.\n If you don't need to parse command-line arguments, you should call `boot` manually.\n See Also: [`post`][chanfig.Config.post]\n Returns:\n self:\n Examples:\n >>> class DataConfig(Config):\n ... def post(self):\n ... if isinstance(self.path, str):\n ... self.path = Config(feature=self.path, label=self.path)\n ... return self\n >>> class BootConfig(Config):\n ... def __init__(self, *args, **kwargs):\n ... super().__init__(*args, **kwargs)\n ... self.dataset = DataConfig(path=\"path\")\n ... def post(self):\n ... if isinstance(self.id, str):\n ... self.id += \"_id\"\n ... return self\n >>> c = BootConfig(id=\"boot\")\n >>> c.boot()\n BootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n )\n \"\"\"\nfor value in self.values():\nif isinstance(value, Config):\nvalue.boot()\nself.post()\nreturn self\ndef parse(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse` will try to parse all command-line arguments,\n you don't need to pre-define them but typos may cause trouble.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse`][chanfig.ConfigParser.parse]: Implementation of `parse`.\n [`parse_config`][chanfig.Config.parse_config]: Only parse valid config arguments.\n Examples:\n >>> c = Config(a=0)\n >>> c.dict()\n {'a': 0}\n >>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\ndef parse_config(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse_config` only parse command-line arguments that is in defined in `Config`.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse_config`][chanfig.ConfigParser.parse_config]: Implementation of `parse_config`.\n [`parse`][chanfig.Config.parse]: Parse all command-line arguments.\n Examples:\n >>> c = Config(a=0, b=0, c=0)\n >>> c.dict()\n {'a': 0, 'b': 0, 'c': 0}\n >>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse_config(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\ndef add_argument(self, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Add an argument to `ConfigParser`.\n Note that value defined in `Config` will override the default value defined in `add_argument`.\n Examples:\n >>> c = Config(a=0, c=1)\n >>> arg = c.add_argument(\"--a\", type=int, default=1)\n >>> arg = c.add_argument(\"--b\", type=int, default=2)\n >>> c.parse(['--c', '4']).dict()\n {'a': 1, 'c': 4, 'b': 2}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nreturn self.getattr(\"parser\").add_argument(*args, **kwargs)\ndef freeze(self, recursive: bool = True) -> Config:\nr\"\"\"\n Freeze `Config`.\n Args:\n recursive:\n **Alias**:\n + `lock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.i.getattr('frozen')\n False\n >>> c.lock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n True\n \"\"\"\n@wraps(self.freeze)\ndef freeze(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", True)\nif recursive:\nself.apply_(freeze)\nelse:\nfreeze(self)\nreturn self\ndef lock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`freeze`][chanfig.Config.freeze].\n \"\"\"\nreturn self.freeze(recursive=recursive)\n@contextmanager\ndef locked(self):\n\"\"\"\n Context manager which temporarily locks `Config`.\n Examples:\n >>> c = Config()\n >>> with c.locked():\n ... c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.i.d = 1013\n >>> c.dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.freeze()\nyield self\nfinally:\nif not was_frozen:\nself.defrost()\ndef defrost(self, recursive: bool = True) -> Config:\nr\"\"\"\n Defrost `Config`.\n Args:\n recursive:\n **Alias**:\n + `unlock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.defrost(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n False\n >>> c.i.getattr('frozen')\n True\n >>> c.unlock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n False\n \"\"\"\n@wraps(self.defrost)\ndef defrost(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", False)\nif recursive:\nself.apply_(defrost)\nelse:\ndefrost(self)\nreturn self\ndef unlock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`defrost`][chanfig.Config.defrost].\n \"\"\"\nreturn self.defrost(recursive=recursive)\n@contextmanager\ndef unlocked(self):\n\"\"\"\n Context manager which temporarily unlocks `Config`.\n Examples:\n >>> c = Config()\n >>> c.freeze().dict()\n {}\n >>> with c.unlocked():\n ... c['i.d'] = 1013\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.defrost()\nyield self\nfinally:\nif was_frozen:\nself.freeze()\ndef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `Config`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `Config` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `Config` does not contain `name` and `default`/`default_factory` is not specified.\n Examples:\n >>> d = Config(**{\"i.d\": 1013})\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.f\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.f\n >>> d.freeze()\n Config(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n )\n >>> d.f\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'f'\n >>> d[\"f.n\"]\n Traceback (most recent call last):\n KeyError: 'f.n'\n \"\"\"\nif not self.hasattr(\"default_factory\"): # did not call super().__init__() in sub-class\nself.setattr(\"default_factory\", Config)\nif name in self or not self.getattr(\"frozen\", False):\nreturn super().get(name, default, fallback)\nraise KeyError(name)\n@frozen_check\ndef set(\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `Config`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Raises:\n ValueError: If `Config` is frozen.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n \"\"\"\nreturn super().set(name, value, convert_mapping)\n@frozen_check\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `Config`.\n Args:\n name:\n Examples:\n >>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> \"i.d\" in d\n False\n >>> d.i.d\n Config(<class 'chanfig.config.Config'>, )\n >>> \"i.d\" in d\n True\n >>> del d.f.n\n >>> d.f.n\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.c\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'c'\n \"\"\"\nsuper().delete(name)\n@frozen_check\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `Config`.\n Args:\n name:\n default:\n Returns:\n value: If `Config` does not contain `name`, return `default`.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n >>> c.pop('i.d', True)\n True\n >>> c.freeze().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n \"\"\"\nreturn super().pop(name, default)\nadd_argument(*args, **kwargs)","text":"Add an argument to ConfigParser.
Note that value defined in Config will override the default value defined in add_argument.
Examples:
Python Console Session>>> c = Config(a=0, c=1)\n>>> arg = c.add_argument(\"--a\", type=int, default=1)\n>>> arg = c.add_argument(\"--b\", type=int, default=2)\n>>> c.parse(['--c', '4']).dict()\n{'a': 1, 'c': 4, 'b': 2}\nchanfig/config.py Pythondef add_argument(self, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Add an argument to `ConfigParser`.\n Note that value defined in `Config` will override the default value defined in `add_argument`.\n Examples:\n >>> c = Config(a=0, c=1)\n >>> arg = c.add_argument(\"--a\", type=int, default=1)\n >>> arg = c.add_argument(\"--b\", type=int, default=2)\n >>> c.parse(['--c', '4']).dict()\n {'a': 1, 'c': 4, 'b': 2}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nreturn self.getattr(\"parser\").add_argument(*args, **kwargs)\nboot()","text":"Apply post recursively.
Sub-config may have their own post method. boot is provided to apply post recursively.
By default, boot is called after Config is parsed. If you don\u2019t need to parse command-line arguments, you should call boot manually.
See Also: post
Returns:
Name Type Descriptionself Config Examples:
Python Console Session>>> class DataConfig(Config):\n... def post(self):\n... if isinstance(self.path, str):\n... self.path = Config(feature=self.path, label=self.path)\n... return self\n>>> class BootConfig(Config):\n... def __init__(self, *args, **kwargs):\n... super().__init__(*args, **kwargs)\n... self.dataset = DataConfig(path=\"path\")\n... def post(self):\n... if isinstance(self.id, str):\n... self.id += \"_id\"\n... return self\n>>> c = BootConfig(id=\"boot\")\n>>> c.boot()\nBootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n)\nchanfig/config.py Pythondef boot(self) -> Config:\nr\"\"\"\n Apply `post` recursively.\n Sub-config may have their own `post` method.\n `boot` is provided to apply `post` recursively.\n By default, `boot` is called after `Config` is parsed.\n If you don't need to parse command-line arguments, you should call `boot` manually.\n See Also: [`post`][chanfig.Config.post]\n Returns:\n self:\n Examples:\n >>> class DataConfig(Config):\n ... def post(self):\n ... if isinstance(self.path, str):\n ... self.path = Config(feature=self.path, label=self.path)\n ... return self\n >>> class BootConfig(Config):\n ... def __init__(self, *args, **kwargs):\n ... super().__init__(*args, **kwargs)\n ... self.dataset = DataConfig(path=\"path\")\n ... def post(self):\n ... if isinstance(self.id, str):\n ... self.id += \"_id\"\n ... return self\n >>> c = BootConfig(id=\"boot\")\n >>> c.boot()\n BootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n )\n \"\"\"\nfor value in self.values():\nif isinstance(value, Config):\nvalue.boot()\nself.post()\nreturn self\ndefrost(recursive=True)","text":"Defrost Config.
Parameters:
Name Type Description Defaultrecursive bool True Alias:
unlockExamples:
Python Console Session>>> c = Config(**{'i.d': 1013})\n>>> c.getattr('frozen')\nFalse\n>>> c.freeze().dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nTrue\n>>> c.defrost(recursive=False).dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nFalse\n>>> c.i.getattr('frozen')\nTrue\n>>> c.unlock().dict() # alias\n{'i': {'d': 1013}}\n>>> c.i.getattr('frozen')\nFalse\nchanfig/config.py Pythondef defrost(self, recursive: bool = True) -> Config:\nr\"\"\"\n Defrost `Config`.\n Args:\n recursive:\n **Alias**:\n + `unlock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.defrost(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n False\n >>> c.i.getattr('frozen')\n True\n >>> c.unlock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n False\n \"\"\"\n@wraps(self.defrost)\ndef defrost(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", False)\nif recursive:\nself.apply_(defrost)\nelse:\ndefrost(self)\nreturn self\ndelete(name)","text":"Delete value from Config.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n>>> d.i.d\n1013\n>>> d.f.n\n'chang'\n>>> d.delete('i.d')\n>>> \"i.d\" in d\nFalse\n>>> d.i.d\nConfig(<class 'chanfig.config.Config'>, )\n>>> \"i.d\" in d\nTrue\n>>> del d.f.n\n>>> d.f.n\nConfig(<class 'chanfig.config.Config'>, )\n>>> del d.c\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'c'\nchanfig/config.py Python@frozen_check\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `Config`.\n Args:\n name:\n Examples:\n >>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> \"i.d\" in d\n False\n >>> d.i.d\n Config(<class 'chanfig.config.Config'>, )\n >>> \"i.d\" in d\n True\n >>> del d.f.n\n >>> d.f.n\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.c\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'c'\n \"\"\"\nsuper().delete(name)\nfreeze(recursive=True)","text":"Freeze Config.
Parameters:
Name Type Description Defaultrecursive bool True Alias:
lockExamples:
Python Console Session>>> c = Config(**{'i.d': 1013})\n>>> c.getattr('frozen')\nFalse\n>>> c.freeze(recursive=False).dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nTrue\n>>> c.i.getattr('frozen')\nFalse\n>>> c.lock().dict() # alias\n{'i': {'d': 1013}}\n>>> c.i.getattr('frozen')\nTrue\nchanfig/config.py Pythondef freeze(self, recursive: bool = True) -> Config:\nr\"\"\"\n Freeze `Config`.\n Args:\n recursive:\n **Alias**:\n + `lock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.i.getattr('frozen')\n False\n >>> c.lock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n True\n \"\"\"\n@wraps(self.freeze)\ndef freeze(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", True)\nif recursive:\nself.apply_(freeze)\nelse:\nfreeze(self)\nreturn self\nget(name, default=None, fallback=None)","text":"Get value from Config.
Note that default has higher priority than default_factory.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If Config does not contain name, return default. If default is not specified, return default_factory().
Raises:
Type DescriptionKeyError If Config does not contain name and default/default_factory is not specified.
Examples:
Python Console Session>>> d = Config(**{\"i.d\": 1013})\n>>> d.get('i.d')\n1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.get('f', 2)\n2\n>>> d.f\nConfig(<class 'chanfig.config.Config'>, )\n>>> del d.f\n>>> d.freeze()\nConfig(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n)\n>>> d.f\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'f'\n>>> d[\"f.n\"]\nTraceback (most recent call last):\nKeyError: 'f.n'\nchanfig/config.py Pythondef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `Config`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `Config` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `Config` does not contain `name` and `default`/`default_factory` is not specified.\n Examples:\n >>> d = Config(**{\"i.d\": 1013})\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.f\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.f\n >>> d.freeze()\n Config(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n )\n >>> d.f\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'f'\n >>> d[\"f.n\"]\n Traceback (most recent call last):\n KeyError: 'f.n'\n \"\"\"\nif not self.hasattr(\"default_factory\"): # did not call super().__init__() in sub-class\nself.setattr(\"default_factory\", Config)\nif name in self or not self.getattr(\"frozen\", False):\nreturn super().get(name, default, fallback)\nraise KeyError(name)\nlock(recursive=True)","text":"Alias of freeze.
chanfig/config.py Pythondef lock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`freeze`][chanfig.Config.freeze].\n \"\"\"\nreturn self.freeze(recursive=recursive)\nlocked()","text":"Context manager which temporarily locks Config.
Examples:
Python Console Session>>> c = Config()\n>>> with c.locked():\n... c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.i.d = 1013\n>>> c.dict()\n{'i': {'d': 1013}}\nchanfig/config.py Python@contextmanager\ndef locked(self):\n\"\"\"\n Context manager which temporarily locks `Config`.\n Examples:\n >>> c = Config()\n >>> with c.locked():\n ... c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.i.d = 1013\n >>> c.dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.freeze()\nyield self\nfinally:\nif not was_frozen:\nself.defrost()\nparse(args=None, default_config=None, no_default_config_action='raise', boot=True)","text":"Parse command-line arguments with ConfigParser.
parse will try to parse all command-line arguments, you don\u2019t need to pre-define them but typos may cause trouble.
By default, this method internally calls Config.boot(). To disable this behaviour, set boot to False.
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to None.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' boot bool If True, call Config.boot() after parsing. Defaults to True.
True See Also chanfig.ConfigParser.parse: Implementation of parse. parse_config: Only parse valid config arguments.
Examples:
Python Console Session>>> c = Config(a=0)\n>>> c.dict()\n{'a': 0}\n>>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/config.py Pythondef parse(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse` will try to parse all command-line arguments,\n you don't need to pre-define them but typos may cause trouble.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse`][chanfig.ConfigParser.parse]: Implementation of `parse`.\n [`parse_config`][chanfig.Config.parse_config]: Only parse valid config arguments.\n Examples:\n >>> c = Config(a=0)\n >>> c.dict()\n {'a': 0}\n >>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\nparse_config(args=None, default_config=None, no_default_config_action='raise', boot=True)","text":"Parse command-line arguments with ConfigParser.
parse_config only parse command-line arguments that is in defined in Config.
By default, this method internally calls Config.boot(). To disable this behaviour, set boot to False.
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to None.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' boot bool If True, call Config.boot() after parsing. Defaults to True.
True See Also chanfig.ConfigParser.parse_config: Implementation of parse_config. parse: Parse all command-line arguments.
Examples:
Python Console Session>>> c = Config(a=0, b=0, c=0)\n>>> c.dict()\n{'a': 0, 'b': 0, 'c': 0}\n>>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/config.py Pythondef parse_config(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse_config` only parse command-line arguments that is in defined in `Config`.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse_config`][chanfig.ConfigParser.parse_config]: Implementation of `parse_config`.\n [`parse`][chanfig.Config.parse]: Parse all command-line arguments.\n Examples:\n >>> c = Config(a=0, b=0, c=0)\n >>> c.dict()\n {'a': 0, 'b': 0, 'c': 0}\n >>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse_config(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\npop(name, default=Null)","text":"Pop value from Config.
Parameters:
Name Type Description Defaultname Any required default Any Null Returns:
Name Type Descriptionvalue Any If Config does not contain name, return default.
Examples:
Python Console Session>>> c = Config()\n>>> c['i.d'] = 1013\n>>> c.pop('i.d')\n1013\n>>> c.pop('i.d', True)\nTrue\n>>> c.freeze().dict()\n{'i': {}}\n>>> c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.defrost().dict()\n{'i': {}}\n>>> c['i.d'] = 1013\n>>> c.pop('i.d')\n1013\nchanfig/config.py Python@frozen_check\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `Config`.\n Args:\n name:\n default:\n Returns:\n value: If `Config` does not contain `name`, return `default`.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n >>> c.pop('i.d', True)\n True\n >>> c.freeze().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n \"\"\"\nreturn super().pop(name, default)\npost()","text":"Post process of Config.
Some Config may need to do some post process after Config is initialised. post is provided for this lazy-initialisation purpose.
By default, post calls interpolate to perform variable interpolation.
Note that you should always call boot to apply post rather than calling post directly, as boot recursively call post on sub-configs.
See Also: boot
Returns:
Name Type Descriptionself Config | None Examples:
Python Console Session>>> class PostConfig(Config):\n... def post(self):\n... if isinstance(self.data, str):\n... self.data = Config(feature=self.data, label=self.data)\n... return self\n>>> c = PostConfig(data=\"path\")\n>>> c.post()\nPostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n)\nchanfig/config.py Pythondef post(self) -> Config | None:\nr\"\"\"\n Post process of `Config`.\n Some `Config` may need to do some post process after `Config` is initialised.\n `post` is provided for this lazy-initialisation purpose.\n By default, `post` calls `interpolate` to perform variable interpolation.\n Note that you should always call `boot` to apply `post` rather than calling `post` directly,\n as `boot` recursively call `post` on sub-configs.\n See Also: [`boot`][chanfig.Config.boot]\n Returns:\n self:\n Examples:\n >>> class PostConfig(Config):\n ... def post(self):\n ... if isinstance(self.data, str):\n ... self.data = Config(feature=self.data, label=self.data)\n ... return self\n >>> c = PostConfig(data=\"path\")\n >>> c.post()\n PostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n \"\"\"\nself.interpolate()\nself.validate()\nreturn self\nset(name, value, convert_mapping=None)","text":"Set value of Config.
Parameters:
Name Type Description Defaultname Any required value Any required convert_mapping bool | None Whether to convert Mapping to NestedDict. Defaults to self.convert_mapping.
None Raises:
Type DescriptionValueError If Config is frozen.
Examples:
Python Console Session>>> c = Config()\n>>> c['i.d'] = 1013\n>>> c.i.d\n1013\n>>> c.freeze().dict()\n{'i': {'d': 1013}}\n>>> c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.defrost().dict()\n{'i': {'d': 1013}}\n>>> c['i.d'] = 1013\n>>> c.i.d\n1013\nchanfig/config.py Python@frozen_check\ndef set(\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `Config`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Raises:\n ValueError: If `Config` is frozen.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n \"\"\"\nreturn super().set(name, value, convert_mapping)\nunlock(recursive=True)","text":"Alias of defrost.
chanfig/config.py Pythondef unlock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`defrost`][chanfig.Config.defrost].\n \"\"\"\nreturn self.defrost(recursive=recursive)\nunlocked()","text":"Context manager which temporarily unlocks Config.
Examples:
Python Console Session>>> c = Config()\n>>> c.freeze().dict()\n{}\n>>> with c.unlocked():\n... c['i.d'] = 1013\n>>> c.defrost().dict()\n{'i': {'d': 1013}}\nchanfig/config.py Python@contextmanager\ndef unlocked(self):\n\"\"\"\n Context manager which temporarily unlocks `Config`.\n Examples:\n >>> c = Config()\n >>> c.freeze().dict()\n {}\n >>> with c.unlocked():\n ... c['i.d'] = 1013\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.defrost()\nyield self\nfinally:\nif was_frozen:\nself.freeze()\nfrozen_check(func)","text":"Decorator check if the object is frozen.
Source code inchanfig/config.py Pythondef frozen_check(func: Callable):\nr\"\"\"\n Decorator check if the object is frozen.\n \"\"\"\n@wraps(func)\ndef decorator(self, *args: Any, **kwargs: Any):\nif self.getattr(\"frozen\", False):\nraise ValueError(\"Attempting to alter a frozen config. Run config.defrost() to defrost first.\")\nreturn func(self, *args, **kwargs)\nreturn decorator\n Bases: FlatDict
DefaultDict inherits from FlatDict and incorporates support of default_factory in the same manner as collections.defaultdict. If default_factory is not None, the value will be set to default_factory() when you access a key that does not exist in DefaultDict.
You may specify DefaultDict(default_factory=FlatDict) when creating DefaultDict or by calling dict.setattr('default_factory', FlatDict) for existing DefaultDict objects.
Note that just like collections.defaultdict, default_factory() is called without any arguments.
Attributes:
Name Type Descriptiondefault_factory Optional[Callable] Default factory for defaultdict behaviour.
Raises:
Type DescriptionTypeError If default_factory is not callable.
Unlike collections.defaultdict, DefaultDict will not automatically create entries when name starts and ends with __. This is to avoid conflicts with Python magic methods. You can still creates them manually with DefaultDict.fromkeys or DefaultDict.add.
Examples:
Python Console Session>>> d = DefaultDict(list)\n>>> d.a.append(1)\n>>> d.a\n[1]\n>>> d = DefaultDict([])\nTraceback (most recent call last):\nTypeError: `default_factory=[]` must be Callable, but got <class 'list'>.\nchanfig/default_dict.py Pythonclass DefaultDict(FlatDict): # type: ignore\nr\"\"\"\n `DefaultDict` inherits from `FlatDict` and incorporates support of `default_factory`\n in the same manner as `collections.defaultdict`.\n If `default_factory is not None`, the value will be set to `default_factory()`\n when you access a key that does not exist in `DefaultDict`.\n You may specify `DefaultDict(default_factory=FlatDict)` when creating `DefaultDict` or\n by calling `dict.setattr('default_factory', FlatDict)` for existing `DefaultDict` objects.\n Note that just like `collections.defaultdict`, `default_factory()` is called without any arguments.\n Attributes:\n default_factory: Default factory for defaultdict behaviour.\n Raises:\n TypeError: If `default_factory` is not callable.\n Notes:\n Unlike `collections.defaultdict`, `DefaultDict` will not automatically create entries when name starts and ends\n with `__`. This is to avoid conflicts with Python magic methods.\n You can still creates them manually with `DefaultDict.fromkeys` or `DefaultDict.add`.\n Examples:\n >>> d = DefaultDict(list)\n >>> d.a.append(1)\n >>> d.a\n [1]\n >>> d = DefaultDict([])\n Traceback (most recent call last):\n TypeError: `default_factory=[]` must be Callable, but got <class 'list'>.\n \"\"\"\ndefault_factory: Optional[Callable] = None\ndef __init__( # pylint: disable=W1113\nself, default_factory: Callable | None = None, *args: Any, **kwargs: Any\n) -> None:\nsuper().__init__(*args, **kwargs)\nif default_factory is not None:\nif callable(default_factory):\nself.setattr(\"default_factory\", default_factory)\nelse:\nraise TypeError(\nf\"`default_factory={default_factory}` must be Callable, but got {type(default_factory)}.\"\n)\ndef __missing__(self, name: Any, default=Null) -> Any: # pylint: disable=R1710\nif default is Null:\nif self.getattr(\"default_factory\", None) in (None, Null) or (name.startswith(\"__\") and name.endswith(\"__\")):\nraise KeyError(name) from None\ndefault = self.getattr(\"default_factory\")()\nif isinstance(default, FlatDict):\ndefault.__dict__.update(self.__dict__)\nsuper().set(name, default)\nreturn default\ndef __repr__(self) -> str:\nif self.default_factory is None:\nreturn super().__repr__()\nsuper_repr = super().__repr__()[len(self.__class__.__name__) :] # noqa: E203\nif len(super_repr) == 2:\nreturn f\"{self.__class__.__name__}({self.default_factory}, )\"\nreturn f\"{self.__class__.__name__}({self.default_factory},\" + super_repr[1:]\ndef add(self, name: Any):\nr\"\"\"\n Add a new default factory to the dictionary.\n Args:\n name:\n Raises:\n ValueError: If `default_factory` is None.\n Examples:\n >>> d = DefaultDict(default_factory=DefaultDict)\n >>> d.add('d')\n DefaultDict()\n >>> d.get('d')\n DefaultDict()\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n >>> d = DefaultDict()\n >>> d.add('a')\n Traceback (most recent call last):\n ValueError: Cannot add to a DefaultDict with no default_factory\n \"\"\"\nif self.default_factory is None:\nraise ValueError(\"Cannot add to a DefaultDict with no default_factory\")\nself.set(name, self.default_factory()) # pylint: disable=E1102\nreturn self.get(name)\nadd(name)","text":"Add a new default factory to the dictionary.
Parameters:
Name Type Description Defaultname Any required Raises:
Type DescriptionValueError If default_factory is None.
Examples:
Python Console Session>>> d = DefaultDict(default_factory=DefaultDict)\n>>> d.add('d')\nDefaultDict()\n>>> d.get('d')\nDefaultDict()\n>>> d['n'] = 'chang'\n>>> d.n\n'chang'\n>>> d.n = 'liu'\n>>> d['n']\n'liu'\n>>> d = DefaultDict()\n>>> d.add('a')\nTraceback (most recent call last):\nValueError: Cannot add to a DefaultDict with no default_factory\nchanfig/default_dict.py Pythondef add(self, name: Any):\nr\"\"\"\n Add a new default factory to the dictionary.\n Args:\n name:\n Raises:\n ValueError: If `default_factory` is None.\n Examples:\n >>> d = DefaultDict(default_factory=DefaultDict)\n >>> d.add('d')\n DefaultDict()\n >>> d.get('d')\n DefaultDict()\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n >>> d = DefaultDict()\n >>> d.add('a')\n Traceback (most recent call last):\n ValueError: Cannot add to a DefaultDict with no default_factory\n \"\"\"\nif self.default_factory is None:\nraise ValueError(\"Cannot add to a DefaultDict with no default_factory\")\nself.set(name, self.default_factory()) # pylint: disable=E1102\nreturn self.get(name)\n Bases: dict
FlatDict with attribute-style access.
FlatDict inherits from built-in dict.
It comes with many easy to use helper methods, such as merge, sort, difference, intersect.
It also has full support for IO operations, such as json and yaml.
Even better, FlatDict has pytorch support built-in. You can directly call FlatDict.cpu() or FlatDict.to(\"cpu\") to move all torch.Tensor objects across devices.
FlatDict works best with Variable objects. Simply call flat_dict.a = Variable(1); flat_dict.b = flat_dict.a, and their values will be synced.
Even better, FlatDict support variable interpolation. Just set the value of one key to another key (surrounded by braces with $ at the begin, like ${xxx}), and calls flat_dict.interpolate(), FlatDict will interpolate their values and create Variable automatically.
FlatDict has many other easy to use helper methods, such as difference, intersect. And has full support for IO operations, such as json and yaml.
FlatDict also has pytorch support built-in. You can directly call flat_dict.cpu() or flat_dict.to(\"cpu\") to move all torch.Tensor objects across devices.
Attributes:
Name Type Descriptionindent int Indentation level in printing and dumping to json or yaml.
NotesFlatDict rewrite __getattribute__ and __getattr__ to supports attribute-style access to its members. Therefore, all internal attributes should be set and get through flat_dict.setattr and flat_dict.getattr.
Although it is possible to override other internal methods, it is not recommended to do so.
__class__, __dict__, and getattr are reserved and cannot be overrode in any manner.
Examples:
Python Console Session>>> d = FlatDict()\n>>> d.d = 1013\n>>> d['d']\n1013\n>>> d['i'] = 1013\n>>> d.i\n1013\n>>> d.a = Variable(1)\n>>> d.b = d.a\n>>> d.a, d.b\n(1, 1)\n>>> d.a += 1\n>>> d.a, d.b\n(2, 2)\n>>> d.a = 3\n>>> d.a, d.b\n(3, 3)\n>>> d.a = Variable('hello')\n>>> f\"{d.a}, world!\"\n'hello, world!'\n>>> d.a = d.a + ', world!'\n>>> d.b\n'hello, world!'\nchanfig/flat_dict.py Pythonclass FlatDict(dict, metaclass=Dict): # type: ignore\nr\"\"\"\n `FlatDict` with attribute-style access.\n `FlatDict` inherits from built-in `dict`.\n It comes with many easy to use helper methods, such as `merge`, `sort`, `difference`, `intersect`.\n It also has full support for IO operations, such as `json` and `yaml`.\n Even better, `FlatDict` has pytorch support built-in.\n You can directly call `FlatDict.cpu()` or `FlatDict.to(\"cpu\")` to move all `torch.Tensor` objects across devices.\n `FlatDict` works best with `Variable` objects.\n Simply call `flat_dict.a = Variable(1); flat_dict.b = flat_dict.a`, and their values will be synced.\n Even better, `FlatDict` support variable interpolation.\n Just set the value of one key to another key (surrounded by braces with $ at the begin, like ${xxx}),\n and calls `flat_dict.interpolate()`, `FlatDict` will interpolate their values and create `Variable` automatically.\n `FlatDict` has many other easy to use helper methods, such as `difference`, `intersect`.\n And has full support for IO operations, such as `json` and `yaml`.\n `FlatDict` also has pytorch support built-in.\n You can directly call `flat_dict.cpu()` or `flat_dict.to(\"cpu\")` to move all `torch.Tensor` objects across devices.\n Attributes:\n indent: Indentation level in printing and dumping to json or yaml.\n Notes:\n `FlatDict` rewrite `__getattribute__` and `__getattr__` to supports attribute-style access to its members.\n Therefore, all internal attributes should be set and get through `flat_dict.setattr` and `flat_dict.getattr`.\n Although it is possible to override other internal methods, it is not recommended to do so.\n `__class__`, `__dict__`, and `getattr` are reserved and cannot be overrode in any manner.\n Examples:\n >>> d = FlatDict()\n >>> d.d = 1013\n >>> d['d']\n 1013\n >>> d['i'] = 1013\n >>> d.i\n 1013\n >>> d.a = Variable(1)\n >>> d.b = d.a\n >>> d.a, d.b\n (1, 1)\n >>> d.a += 1\n >>> d.a, d.b\n (2, 2)\n >>> d.a = 3\n >>> d.a, d.b\n (3, 3)\n >>> d.a = Variable('hello')\n >>> f\"{d.a}, world!\"\n 'hello, world!'\n >>> d.a = d.a + ', world!'\n >>> d.b\n 'hello, world!'\n \"\"\"\n# pylint: disable=R0904\nindent: int = 2\ndef __post_init__(self, *args, **kwargs) -> None:\npass\ndef __getattribute__(self, name: Any) -> Any:\nif (name not in (\"getattr\",) and not (name.startswith(\"__\") and name.endswith(\"__\"))) and name in self:\nreturn self.get(name)\nreturn super().__getattribute__(name)\ndef get(self, name: Any, default: Any = None) -> Any:\nr\"\"\"\n Get value from `FlatDict`.\n Args:\n name:\n default:\n Returns:\n value:\n If `FlatDict` does not contain `name`, return `default`.\n Raises:\n KeyError: If `FlatDict` does not contain `name` and `default` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = FlatDict(d=1013)\n >>> d.get('d')\n 1013\n >>> d['d']\n 1013\n >>> d.d\n 1013\n >>> d.get('d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('f')\n >>> d.get('f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\nif name in self:\nreturn dict.__getitem__(self, name)\nif default is not Null:\nreturn default\nreturn self.__missing__(name)\ndef __getitem__(self, name: Any) -> Any:\nreturn self.get(name, default=Null)\ndef __getattr__(self, name: Any) -> Any:\ntry:\nreturn self.get(name, default=Null)\nexcept KeyError:\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef set(self, name: Any, value: Any) -> None:\nr\"\"\"\n Set value of `FlatDict`.\n Args:\n name:\n value:\n Examples:\n >>> d = FlatDict()\n >>> d.set('d', 1013)\n >>> d.get('d')\n 1013\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n \"\"\"\nif name in self and isinstance(self.get(name), Variable):\nself.get(name).set(value)\nelse:\ndict.__setitem__(self, name, value)\ndef __setitem__(self, name: Any, value: Any) -> None:\nself.set(name, value)\ndef __setattr__(self, name: Any, value: Any) -> None:\nself.set(name, value)\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict(d=1016, n='chang')\n >>> d.d\n 1016\n >>> d.n\n 'chang'\n >>> d.delete('d')\n >>> d.d\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'd'\n >>> del d.n\n >>> d.n\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'n'\n >>> del d.f\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'f'\n \"\"\"\ndict.__delitem__(self, name)\ndef __delitem__(self, name: Any) -> None:\nreturn self.delete(name)\ndef __delattr__(self, name: Any) -> None:\ntry:\nself.delete(name)\nexcept KeyError:\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef __missing__(self, name: Any) -> Any: # pylint: disable=R1710\nraise KeyError(name)\ndef validate(self) -> None:\nr\"\"\"\n Validate `FlatDict`.\n Raises:\n TypeError: If value is not of the type declared in class annotations.\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n >>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\n Traceback (most recent call last):\n ValueError: 'n' has invalid value. Value chang is not valid.\n \"\"\"\nself._validate(self)\n@staticmethod\ndef _validate(obj) -> None:\nif isinstance(obj, FlatDict):\nannotations = get_annotations(obj)\nfor name, value in obj.items():\nif annotations and name in annotations and not isvalid(value, annotations[name]):\nraise TypeError(f\"'{name}' has invalid type. Value {value} is not of type {annotations[name]}.\")\nif isinstance(value, Variable):\ntry:\nvalue.validate()\nexcept TypeError as exc:\nraise TypeError(f\"'{name}' has invalid type. {exc}\") from None\nexcept ValueError as exc:\nraise ValueError(f\"'{name}' has invalid value. {exc}\") from None\ndef getattr(self, name: str, default: Any = Null) -> Any:\nr\"\"\"\n Get attribute of `FlatDict`.\n Note that it won't retrieve value in `FlatDict`,\n Args:\n name:\n default:\n Returns:\n value: If `FlatDict` does not contain `name`, return `default`.\n Raises:\n AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.\n Examples:\n >>> d = FlatDict(a=1)\n >>> d.get('a')\n 1\n >>> d.getattr('a')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'a'\n >>> d.getattr('b', 2)\n 2\n >>> d.setattr('b', 3)\n >>> d.getattr('b')\n 3\n \"\"\"\ntry:\nif name in self.__dict__:\nreturn self.__dict__[name]\nif name in self.__class__.__dict__:\nreturn self.__class__.__dict__[name]\nreturn super().getattr(name, default) # type: ignore\nexcept AttributeError:\nif default is not Null:\nreturn default\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef setattr(self, name: str, value: Any) -> None:\nr\"\"\"\n Set attribute of `FlatDict`.\n Note that it won't alter values in `FlatDict`.\n Args:\n name:\n value:\n Warns:\n RuntimeWarning: If name already exists in `FlatDict`.\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('attr', 'value')\n >>> d.getattr('attr')\n 'value'\n >>> d.set('d', 1013)\n >>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n >>> d.get('d')\n 1013\n >>> d.d\n 1013\n >>> d.getattr('d')\n 1031\n \"\"\"\nif name in self:\nwarn(\nf\"{name} already exists in {self.__class__.__name__}.\\n\"\nf\"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.\",\nRuntimeWarning,\n)\nself.__dict__[name] = value\ndef delattr(self, name: str) -> None:\nr\"\"\"\n Delete attribute of `FlatDict`.\n Note that it won't delete values in `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.getattr('name')\n 'chang'\n >>> d.delattr('name')\n >>> d.getattr('name')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'name'\n \"\"\"\ndel self.__dict__[name]\ndef hasattr(self, name: str) -> bool:\nr\"\"\"\n Determine if an attribute exists in `FlatDict`.\n Args:\n name:\n Returns:\n (bool):\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.hasattr('name')\n True\n >>> d.delattr('name')\n >>> d.hasattr('name')\n False\n \"\"\"\ntry:\nif name in self.__dict__ or name in self.__class__.__dict__:\nreturn True\nreturn super().hasattr(name) # type: ignore\nexcept AttributeError:\nreturn False\ndef dict(self, cls: Callable = dict) -> Mapping:\nr\"\"\"\n Convert `FlatDict` to other `Mapping`.\n Args:\n cls: Target class to be converted to.\n Returns:\n (Mapping):\n See Also:\n [`to_dict`][chanfig.flat_dict.to_dict]: Implementation of `dict`.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn cls(to_dict(self))\n@classmethod\ndef from_dict(cls, obj: Mapping | Sequence) -> Any: # pylint: disable=R0911\nr\"\"\"\n Convert `Mapping` or `Sequence` to `FlatDict`.\n Examples:\n >>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n >>> FlatDict.from_dict({1, 2, 3})\n Traceback (most recent call last):\n TypeError: Expected Mapping or Sequence, but got <class 'set'>.\n \"\"\"\nif obj is None:\nreturn cls()\nif issubclass(cls, FlatDict):\ncls = cls.empty # type: ignore # pylint: disable=W0642\nif isinstance(obj, Mapping):\nreturn cls(obj)\nif isinstance(obj, Sequence):\ntry:\nreturn cls(obj)\nexcept ValueError:\nreturn [cls(json) for json in obj]\nraise TypeError(f\"Expected Mapping or Sequence, but got {type(obj)}.\")\ndef sort(self, key: Callable | None = None, reverse: bool = False) -> FlatDict:\nr\"\"\"\n Sort `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d = FlatDict(b=2, c=3, a=1)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> a = [1]\n >>> d = FlatDict(z=0, a=a)\n >>> a.append(2)\n >>> d.sort().dict()\n {'a': [1, 2], 'z': 0}\n \"\"\"\nitems = sorted(self.items(), key=key, reverse=reverse)\nself.clear()\nfor k, v in items:\nself[k] = v\nreturn self\ndef interpolate(self, use_variable: bool = True, interpolators: MutableMapping | None = None) -> FlatDict:\nr\"\"\"\n Perform Variable interpolation.\n Variable interpolation allows you to set the value of one key to be the value of another key easily.\n Args:\n use_variable: Whether to convert values to `Variable` objects.\n interpolators: Mapping contains values for interpolation. Defaults to `self`.\n Raises:\n ValueError: If value is not interpolatable.\n ValueError: If reference to itself.\n ValueError: If has circular reference.\n See Also:\n [Variable][`chanfig.Variable`]: Mutable wrapper of immutable objects.\n Examples:\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n >>> d.interpolate().dict()\n {'a': 1, 'b': 1, 'c': '1.1'}\n >>> isinstance(d.a, Variable)\n True\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 2, 'c': '1.1'}\n >>> d.a is d.b\n True\n >>> d.b is d.c\n False\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${b}'}\n >>> d.interpolate(False).dict()\n {'a': 1, 'b': 1, 'c': 1}\n >>> isinstance(d.a, Variable)\n False\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 1, 'c': 1}\n >>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Cannot interpolate b to itself.\n >>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Circular reference found: a->b->c->d->a.\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n ).\n \"\"\"\ninterpolators = interpolators or self\nplaceholders: dict[str, list[str]] = {}\nfor key, value in self.all_items():\nif isinstance(value, list):\nfor v in value:\nself.find_placeholders(key, v, placeholders)\nelif isinstance(value, Mapping):\nfor v in value.values():\nself.find_placeholders(key, v, placeholders)\nelse:\nself.find_placeholders(key, value, placeholders)\ncircular_references = find_circular_reference(placeholders)\nif circular_references:\nraise ValueError(f\"Circular reference found: {'->'.join(circular_references)}.\")\nif use_variable:\nplaceholder_names = {i for j in placeholders.values() for i in j}\nfor name in list(placeholder_names.difference(placeholders.keys())):\nif name not in interpolators:\nraise ValueError(f\"{name} is not found in {interpolators}.\")\nif not isinstance(interpolators[name], Variable):\ninterpolators[name] = Variable(interpolators[name])\nfor key, value in placeholders.items():\nif isinstance(self[key], list):\nfor index, v in enumerate(self[key]):\nself[key][index] = self.substitute(v, interpolators, value)\nelif isinstance(self[key], Mapping):\nfor k, v in self[key].items():\nself[key][k] = self.substitute(v, interpolators, value)\nelse:\nself[key] = self.substitute(self[key], interpolators, value)\nreturn self\n@staticmethod\ndef find_placeholders(key, value, placeholders):\nplaceholder = find_placeholders(value)\nif placeholder:\nfor index, name in enumerate(placeholder):\nif name.startswith(\".\"):\nplaceholder[index] = key.rsplit(\".\", 1)[0] + name\nif key == name:\nraise ValueError(f\"Cannot interpolate {key} to itself.\")\nplaceholders[key] = placeholder\n@staticmethod\ndef substitute(placeholder, interpolators, value):\ntry:\nif len(value) == 1 and placeholder.startswith(\"${\") and placeholder.endswith(\"}\"):\nreturn interpolators[value[0]]\nreturn placeholder.replace(\"$\", \"\").format(**interpolators)\nexcept KeyError as exc:\nraise ValueError(f\"{exc} is not found in {interpolators}.\") from None\ndef merge(self, *args: Any, overwrite: bool = True, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge `other` into `FlatDict`.\n Args:\n *args: `Mapping` or `Sequence` to be merged.\n overwrite: Whether to overwrite existing values.\n **kwargs: `Mapping` to be merged.\n Returns:\n self:\n **Alias**:\n + `union`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.merge(n).dict()\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.merge(l).dict()\n {'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n >>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d = FlatDict()\n >>> d.merge({1: 1, 2: 2, 3:3}).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge(d.clone()).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n {1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\n \"\"\"\nif len(args) == 1:\nargs = args[0]\nif isinstance(args, (PathLike, str, bytes)):\nargs = self.load(args) # type: ignore\nwarn(\n\"merge file is deprecated and maybe removed in a future release. Use `merge_from_file` instead.\",\nPendingDeprecationWarning,\n)\nself._merge(self, args, overwrite=overwrite)\nelif len(args) > 1:\nself._merge(self, args, overwrite=overwrite)\nif kwargs:\nself._merge(self, kwargs, overwrite=overwrite)\nreturn self\n@staticmethod\ndef _merge(this: FlatDict, that: Iterable, overwrite: bool = True) -> Mapping:\nif not that:\nreturn this\nif isinstance(that, Mapping):\nthat = that.items()\nfor key, value in that:\nif key in this and isinstance(this[key], Mapping):\nif isinstance(value, Mapping):\nFlatDict._merge(this[key], value)\nelif overwrite:\nif isinstance(value, FlatDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nelif overwrite or key not in this:\nthis.set(key, value)\nreturn this\ndef union(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`merge`][chanfig.FlatDict.merge].\n \"\"\"\nreturn self.merge(*args, **kwargs)\ndef merge_from_file(self, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge content of `file` into `FlatDict`.\n Args:\n file (File):\n *args: Passed to [`load`][chanfig.FlatDict.load].\n **kwargs: Passed to [`load`][chanfig.FlatDict.load].\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=1)\n >>> d.merge_from_file(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn self.merge(self.load(file, *args, **kwargs))\ndef intersect(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Intersection of `FlatDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n Returns:\n (FlatDict):\n **Alias**:\n + `inter`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.intersect(n).dict()\n {}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.intersect(l).dict()\n {'c': 3}\n >>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n {}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(**{key: value for key, value in other if key in self and self[key] == value}) # type: ignore\ndef inter(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`intersect`][chanfig.FlatDict.intersect].\n \"\"\"\nreturn self.intersect(other, *args, **kwargs)\ndef difference(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Difference between `FlatDict` and `other`.\n Args:\n other:\n Returns:\n (FlatDict):\n **Alias**:\n + `diff`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.difference(n).dict()\n {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.merge(l).difference(\"tests/test.yaml\").dict()\n {}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'b': 'b', 'c': 'c', 'd': 'd'}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(\n**{key: value for key, value in other if key not in self or self[key] != value} # type: ignore\n)\ndef diff(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`difference`][chanfig.FlatDict.difference].\n \"\"\"\nreturn self.difference(other, *args, **kwargs)\ndef to(self, cls: str | TorchDevice | TorchDType) -> FlatDict: # pragma: no cover\nr\"\"\"\n Convert values of `FlatDict` to target `cls`.\n Args:\n cls (str | torch.device | torch.dtype):\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.to(int)\n Traceback (most recent call last):\n TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\n \"\"\"\n# pylint: disable=C0103\nif isinstance(cls, (str, TorchDevice, TorchDType)):\nfor k, v in self.all_items():\nif hasattr(v, \"to\"):\nself[k] = v.to(cls)\nreturn self\nraise TypeError(f\"to() only support torch.dtype and torch.device, but got {cls}.\")\ndef cpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to cpu.\n Returns:\n self:\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.cpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cpu')}\n \"\"\"\nreturn self.to(TorchDevice(\"cpu\"))\ndef gpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to gpu.\n Returns:\n self:\n **Alias**:\n + `cuda`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.gpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n >>> d.cuda().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"cuda\"))\ndef cuda(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`gpu`][chanfig.FlatDict.gpu].\n \"\"\"\nreturn self.gpu()\ndef tpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to tpu.\n Returns:\n self:\n **Alias**:\n + `xla`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.tpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n >>> d.xla().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"xla\"))\ndef xla(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`tpu`][chanfig.FlatDict.tpu].\n \"\"\"\nreturn self.tpu()\ndef copy(self) -> FlatDict:\nr\"\"\"\n Create a shallow copy of `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.copy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': [1]}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nreturn copy(self)\ndef __deepcopy__(self, memo: Mapping | None = None) -> FlatDict:\n# pylint: disable=C0103\nif memo is not None and id(self) in memo:\nreturn memo[id(self)]\nret = self.empty()\nret.__dict__.update(deepcopy(self.__dict__))\nfor k, v in self.items():\nif isinstance(v, FlatDict):\nret[k] = v.deepcopy(memo=memo)\nelse:\nret[k] = deepcopy(v)\nreturn ret\ndef deepcopy(self, memo: Mapping | None = None) -> FlatDict: # pylint: disable=W0613\nr\"\"\"\n Create a deep copy of `FlatDict`.\n Returns:\n (FlatDict):\n **Alias**:\n + `clone`\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.deepcopy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': []}\n >>> c.getattr(\"name\")\n 'Chang'\n >>> d == d.clone() # alias\n True\n \"\"\"\nreturn deepcopy(self)\ndef clone(self, memo: Mapping | None = None) -> FlatDict:\nr\"\"\"\n Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].\n \"\"\"\nreturn self.deepcopy(memo=memo)\ndef save(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.save(\"tests/test.yaml\")\n >>> d.save(\"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... d.save(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nreturn self.yaml(file=file, *args, **kwargs) # type: ignore\nif extension in JSON:\nreturn self.json(file=file, *args, **kwargs) # type: ignore\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\ndef dump(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Alias of [`save`][chanfig.FlatDict.save].\n \"\"\"\nreturn self.save(file, method, *args, **kwargs)\n@classmethod\ndef load( # pylint: disable=W1113\ncls, file: File, method: str | None = None, *args: Any, **kwargs: Any\n) -> FlatDict:\n\"\"\"\n Load `FlatDict` from file.\n Args:\n file: File to load from.\n method: File type, should be in `JSON` or `YAML`.\n Returns:\n (FlatDict):\n Raises:\n ValueError: If load from `IO` and `method` is not specified.\n TypeError: If dump to unsupported extension.\n Examples:\n >>> d = FlatDict.load(\"tests/test.yaml\")\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.load(\"tests/test.conf\")\n Traceback (most recent call last):\n TypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"tests/test.yaml\") as f:\n ... d.load(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when loading from IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when loading from IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in JSON:\nreturn cls.from_json(file, *args, **kwargs)\nif extension in YAML:\nreturn cls.from_yaml(file, *args, **kwargs)\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\ndef json(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to json file.\n This method internally calls `self.jsons()` to generate json string.\n You may overwrite `jsons` in case something is not json serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.json(\"tests/test.json\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(self.jsons(*args, **kwargs))\n@classmethod\ndef from_json(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json file.\n This method internally calls `self.from_jsons()` to construct object from json string.\n You may overwrite `from_jsons` in case something is not json serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict.from_json('tests/test.json')\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_jsons(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_jsons(fp.read(), *args, **kwargs)\ndef jsons(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to json string.\n Returns:\n (str):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.jsons()\n '{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\n \"\"\"\nkwargs.setdefault(\"cls\", JsonEncoder)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn json_dumps(self.dict(), *args, **kwargs)\n@classmethod\ndef from_jsons(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nreturn cls.from_dict(json_loads(string, *args, **kwargs))\ndef yaml(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to yaml file.\n This method internally calls `self.yamls()` to generate yaml string.\n You may overwrite `yamls` in case something is not yaml serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.yaml(\"tests/test.yaml\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nself.yamls(fp, *args, **kwargs)\n@classmethod\ndef from_yaml(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml file.\n This method internally calls `self.from_yamls()` to construct object from yaml string.\n You may overwrite `from_yamls` in case something is not yaml serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yaml('tests/test.yaml').dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nkwargs.setdefault(\"Loader\", YamlLoader)\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_yamls(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_dict(yaml_load(fp, *args, **kwargs))\ndef yamls(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to yaml string.\n Returns:\n (str):\n Examples:\n >>> FlatDict(a=1, b=2, c=3).yamls()\n 'a: 1\\nb: 2\\nc: 3\\n'\n \"\"\"\nkwargs.setdefault(\"Dumper\", YamlDumper)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn yaml_dump(self.dict(), *args, **kwargs) # type: ignore\n@classmethod\ndef from_yamls(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nkwargs.setdefault(\"Loader\", SafeLoader)\nreturn cls.from_dict(yaml_load(string, *args, **kwargs))\n@staticmethod\n@contextmanager\ndef open(file: File, *args: Any, encoding: str = \"utf-8\", **kwargs: Any) -> Generator[IOBase | IO, Any, Any]:\nr\"\"\"\n Open file IO from file path or IO.\n This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.\n Args:\n file: File path or IO.\n *args: Additional arguments passed to `open`.\n Defaults to ().\n **kwargs: Any\n Additional keyword arguments passed to `open`.\n Defaults to {}.\n Yields:\n (Generator[IOBase | IO, Any, Any]):\n Examples:\n >>> with FlatDict.open(\"tests/test.yaml\") as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> io = open(\"tests/test.yaml\")\n >>> with FlatDict.open(io) as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> with FlatDict.open(123, mode=\"w\") as fp:\n ... print(fp.read())\n Traceback (most recent call last):\n TypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\n \"\"\"\nif isinstance(file, (IOBase, IO)):\nyield file\nelif isinstance(file, (PathLike, str, bytes)):\ntry:\nfile = open(file, *args, encoding=encoding, **kwargs) # type: ignore # noqa: SIM115\nyield file # type: ignore\nfinally:\nwith suppress(Exception):\nfile.close() # type: ignore\nelse:\nraise TypeError(f\"expected str, bytes, os.PathLike, IO or IOBase, not {type(file).__name__}\")\n@classmethod\ndef empty(cls, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty `FlatDict`.\n This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.\n As use `type(self)()` in this case would copy all the default values, which might not be desired.\n This method will preserve everything in `FlatDict.__class__.__dict__`.\n Returns:\n (FlatDict):\n See Also:\n [`empty_like`][chanfig.FlatDict.empty_like]\n Examples:\n >>> d = FlatDict(a=[])\n >>> c = d.empty()\n >>> c.dict()\n {}\n \"\"\"\nempty = cls.__new__(cls)\nempty.merge(*args, **kwargs) # pylint: disable=W0212\nreturn empty\ndef empty_like(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty copy of `FlatDict`.\n This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.\n For example, `property`s are saved in `__dict__`, they will keep their original reference after calling this\n method.\n Returns:\n (FlatDict):\n See Also:\n [`empty`][chanfig.FlatDict.empty]\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.empty_like()\n >>> c.dict()\n {}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nempty = self.empty(*args, **kwargs)\nempty.__dict__.update(self.__dict__)\nreturn empty\ndef all_keys(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_keys`][chanfig.NestedDict.all_keys]\n \"\"\"\nyield from self.keys()\ndef all_values(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_values`][chanfig.NestedDict.all_values]\n \"\"\"\nyield from self.values()\ndef all_items(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_items`][chanfig.NestedDict.all_items]\n \"\"\"\nyield from self.items()\ndef dropnull(self) -> FlatDict:\nr\"\"\"\n Drop key-value pairs with `Null` value.\n Returns:\n (FlatDict):\n **Alias**:\n + `dropna`\n Examples:\n >>> d = FlatDict(a=Null, b=Null, c=3)\n >>> d.dict()\n {'a': Null, 'b': Null, 'c': 3}\n >>> d.dropnull().dict()\n {'c': 3}\n >>> d.dropna().dict() # alias\n {'c': 3}\n \"\"\"\nreturn self.empty({k: v for k, v in self.all_items() if v is not Null})\ndef dropna(self) -> FlatDict:\nr\"\"\"\n Alias of [`dropnull`][chanfig.FlatDict.dropnull].\n \"\"\"\nreturn self.dropnull()\n@staticmethod\ndef extra_repr() -> str: # pylint: disable=C0116\nreturn \"\"\ndef __repr__(self) -> str:\nextra_lines = []\nextra_repr = self.extra_repr()\n# empty string will be split into list ['']\nif extra_repr:\nextra_lines = extra_repr.split(\"\\n\")\nchild_lines = []\nfor key, value in self.items():\nkey_repr = repr(key)\nvalue_repr = repr(value)\nvalue_repr = self._add_indent(value_repr)\nchild_lines.append(f\"({key_repr}): {value_repr}\")\n# child_lines.append(f\"{key_repr}: {value_repr}\")\nlines = extra_lines + child_lines\nmain_repr = self.__class__.__name__ + \"(\"\nif lines:\n# simple one-liner info, which most builtin Modules will use\nif len(extra_lines) == 1 and not child_lines:\nmain_repr += extra_lines[0]\nelif len(child_lines) == 1 and not extra_lines and len(child_lines[0]) < 10:\nmain_repr += child_lines[0]\nelse:\nmain_repr += \"\\n \" + \"\\n \".join(lines) + \"\\n\"\nmain_repr += \")\"\nreturn main_repr\ndef _add_indent(self, text: str) -> str:\nlines = text.split(\"\\n\")\n# don't do anything for single-line stuff\nif len(lines) == 1:\nreturn text\nfirst = lines.pop(0)\nlines = [(self.getattr(\"indent\", 2) * \" \") + line for line in lines]\ntext = \"\\n\".join(lines)\ntext = first + \"\\n\" + text\nreturn text\ndef __format__(self, format_spec: str) -> str:\nreturn repr(self.empty({k: v.__format__(format_spec) for k, v in self.all_items()}))\ndef __hash__(self):\nreturn hash(frozenset(self.items()))\ndef _ipython_display_(self): # pragma: no cover\nreturn repr(self)\ndef _ipython_canary_method_should_not_exist_(self): # pragma: no cover\nreturn None\ndef aihwerij235234ljsdnp34ksodfipwoe234234jlskjdf(self): # pragma: no cover\nreturn None\ndef __rich__(self): # pragma: no cover\nreturn self.__repr__()\nall_items()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_items
chanfig/flat_dict.py Pythondef all_items(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_items`][chanfig.NestedDict.all_items]\n \"\"\"\nyield from self.items()\nall_keys()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_keys
chanfig/flat_dict.py Pythondef all_keys(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_keys`][chanfig.NestedDict.all_keys]\n \"\"\"\nyield from self.keys()\nall_values()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_values
chanfig/flat_dict.py Pythondef all_values(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_values`][chanfig.NestedDict.all_values]\n \"\"\"\nyield from self.values()\nclone(memo=None)","text":"Alias of deepcopy.
chanfig/flat_dict.py Pythondef clone(self, memo: Mapping | None = None) -> FlatDict:\nr\"\"\"\n Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].\n \"\"\"\nreturn self.deepcopy(memo=memo)\ncopy()","text":"Create a shallow copy of FlatDict.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.copy()\n>>> c.dict()\n{'a': []}\n>>> d.a.append(1)\n>>> c.dict()\n{'a': [1]}\n>>> c.getattr(\"name\")\n'Chang'\nchanfig/flat_dict.py Pythondef copy(self) -> FlatDict:\nr\"\"\"\n Create a shallow copy of `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.copy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': [1]}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nreturn copy(self)\ncpu()","text":"Move all tensors to cpu.
Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.cpu().dict()\n{'a': tensor(1, device='cpu')}\nchanfig/flat_dict.py Pythondef cpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to cpu.\n Returns:\n self:\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.cpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cpu')}\n \"\"\"\nreturn self.to(TorchDevice(\"cpu\"))\ncuda()","text":"Alias of gpu.
chanfig/flat_dict.py Pythondef cuda(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`gpu`][chanfig.FlatDict.gpu].\n \"\"\"\nreturn self.gpu()\ndeepcopy(memo=None)","text":"Create a deep copy of FlatDict.
Returns:
Type DescriptionFlatDict Alias:
cloneExamples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.deepcopy()\n>>> c.dict()\n{'a': []}\n>>> d.a.append(1)\n>>> c.dict()\n{'a': []}\n>>> c.getattr(\"name\")\n'Chang'\n>>> d == d.clone() # alias\nTrue\nchanfig/flat_dict.py Pythondef deepcopy(self, memo: Mapping | None = None) -> FlatDict: # pylint: disable=W0613\nr\"\"\"\n Create a deep copy of `FlatDict`.\n Returns:\n (FlatDict):\n **Alias**:\n + `clone`\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.deepcopy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': []}\n >>> c.getattr(\"name\")\n 'Chang'\n >>> d == d.clone() # alias\n True\n \"\"\"\nreturn deepcopy(self)\ndelattr(name)","text":"Delete attribute of FlatDict.
Note that it won\u2019t delete values in FlatDict.
Parameters:
Name Type Description Defaultname str required Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('name', 'chang')\n>>> d.getattr('name')\n'chang'\n>>> d.delattr('name')\n>>> d.getattr('name')\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'name'\nchanfig/flat_dict.py Pythondef delattr(self, name: str) -> None:\nr\"\"\"\n Delete attribute of `FlatDict`.\n Note that it won't delete values in `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.getattr('name')\n 'chang'\n >>> d.delattr('name')\n >>> d.getattr('name')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'name'\n \"\"\"\ndel self.__dict__[name]\ndelete(name)","text":"Delete value from FlatDict.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = FlatDict(d=1016, n='chang')\n>>> d.d\n1016\n>>> d.n\n'chang'\n>>> d.delete('d')\n>>> d.d\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'd'\n>>> del d.n\n>>> d.n\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'n'\n>>> del d.f\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'f'\nchanfig/flat_dict.py Pythondef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict(d=1016, n='chang')\n >>> d.d\n 1016\n >>> d.n\n 'chang'\n >>> d.delete('d')\n >>> d.d\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'd'\n >>> del d.n\n >>> d.n\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'n'\n >>> del d.f\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'f'\n \"\"\"\ndict.__delitem__(self, name)\ndict(cls=dict)","text":"Convert FlatDict to other Mapping.
Parameters:
Name Type Description Defaultcls Callable Target class to be converted to.
dict Returns:
Type DescriptionMapping See Also to_dict: Implementation of dict.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Pythondef dict(self, cls: Callable = dict) -> Mapping:\nr\"\"\"\n Convert `FlatDict` to other `Mapping`.\n Args:\n cls: Target class to be converted to.\n Returns:\n (Mapping):\n See Also:\n [`to_dict`][chanfig.flat_dict.to_dict]: Implementation of `dict`.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn cls(to_dict(self))\ndiff(other, *args, **kwargs)","text":"Alias of difference.
chanfig/flat_dict.py Pythondef diff(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`difference`][chanfig.FlatDict.difference].\n \"\"\"\nreturn self.difference(other, *args, **kwargs)\ndifference(other)","text":"Difference between FlatDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required Returns:
Type DescriptionFlatDict Alias:
diffExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.difference(n).dict()\n{'b': 'b', 'c': 'c', 'd': 'd'}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.difference(l).dict()\n{'d': 4}\n>>> d.merge(l).difference(\"tests/test.yaml\").dict()\n{}\n>>> d.difference(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n>>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n{'b': 'b', 'c': 'c', 'd': 'd'}\nchanfig/flat_dict.py Pythondef difference(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Difference between `FlatDict` and `other`.\n Args:\n other:\n Returns:\n (FlatDict):\n **Alias**:\n + `diff`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.difference(n).dict()\n {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.merge(l).difference(\"tests/test.yaml\").dict()\n {}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'b': 'b', 'c': 'c', 'd': 'd'}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(\n**{key: value for key, value in other if key not in self or self[key] != value} # type: ignore\n)\ndropna()","text":"Alias of dropnull.
chanfig/flat_dict.py Pythondef dropna(self) -> FlatDict:\nr\"\"\"\n Alias of [`dropnull`][chanfig.FlatDict.dropnull].\n \"\"\"\nreturn self.dropnull()\ndropnull()","text":"Drop key-value pairs with Null value.
Returns:
Type DescriptionFlatDict Alias:
dropnaExamples:
Python Console Session>>> d = FlatDict(a=Null, b=Null, c=3)\n>>> d.dict()\n{'a': Null, 'b': Null, 'c': 3}\n>>> d.dropnull().dict()\n{'c': 3}\n>>> d.dropna().dict() # alias\n{'c': 3}\nchanfig/flat_dict.py Pythondef dropnull(self) -> FlatDict:\nr\"\"\"\n Drop key-value pairs with `Null` value.\n Returns:\n (FlatDict):\n **Alias**:\n + `dropna`\n Examples:\n >>> d = FlatDict(a=Null, b=Null, c=3)\n >>> d.dict()\n {'a': Null, 'b': Null, 'c': 3}\n >>> d.dropnull().dict()\n {'c': 3}\n >>> d.dropna().dict() # alias\n {'c': 3}\n \"\"\"\nreturn self.empty({k: v for k, v in self.all_items() if v is not Null})\ndump(file, method=None, *args, **kwargs)","text":"Alias of save.
chanfig/flat_dict.py Pythondef dump(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Alias of [`save`][chanfig.FlatDict.save].\n \"\"\"\nreturn self.save(file, method, *args, **kwargs)\nempty(*args, **kwargs) classmethod","text":"Initialise an empty FlatDict.
This method is helpful when you inheriting FlatDict with default values defined in __init__(). As use type(self)() in this case would copy all the default values, which might not be desired.
This method will preserve everything in FlatDict.__class__.__dict__.
Returns:
Type DescriptionFlatDict See Also empty_like
Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> c = d.empty()\n>>> c.dict()\n{}\nchanfig/flat_dict.py Python@classmethod\ndef empty(cls, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty `FlatDict`.\n This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.\n As use `type(self)()` in this case would copy all the default values, which might not be desired.\n This method will preserve everything in `FlatDict.__class__.__dict__`.\n Returns:\n (FlatDict):\n See Also:\n [`empty_like`][chanfig.FlatDict.empty_like]\n Examples:\n >>> d = FlatDict(a=[])\n >>> c = d.empty()\n >>> c.dict()\n {}\n \"\"\"\nempty = cls.__new__(cls)\nempty.merge(*args, **kwargs) # pylint: disable=W0212\nreturn empty\nempty_like(*args, **kwargs)","text":"Initialise an empty copy of FlatDict.
This method will preserve everything in FlatDict.__class__.__dict__ and FlatDict.__dict__.
For example, propertys are saved in __dict__, they will keep their original reference after calling this method.
Returns:
Type DescriptionFlatDict See Also empty
Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.empty_like()\n>>> c.dict()\n{}\n>>> c.getattr(\"name\")\n'Chang'\nchanfig/flat_dict.py Pythondef empty_like(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty copy of `FlatDict`.\n This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.\n For example, `property`s are saved in `__dict__`, they will keep their original reference after calling this\n method.\n Returns:\n (FlatDict):\n See Also:\n [`empty`][chanfig.FlatDict.empty]\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.empty_like()\n >>> c.dict()\n {}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nempty = self.empty(*args, **kwargs)\nempty.__dict__.update(self.__dict__)\nreturn empty\nfrom_dict(obj) classmethod","text":"Convert Mapping or Sequence to FlatDict.
Examples:
Python Console Session>>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\nFlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\n>>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\nFlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\n>>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n>>> FlatDict.from_dict({1, 2, 3})\nTraceback (most recent call last):\nTypeError: Expected Mapping or Sequence, but got <class 'set'>.\nchanfig/flat_dict.py Python@classmethod\ndef from_dict(cls, obj: Mapping | Sequence) -> Any: # pylint: disable=R0911\nr\"\"\"\n Convert `Mapping` or `Sequence` to `FlatDict`.\n Examples:\n >>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n >>> FlatDict.from_dict({1, 2, 3})\n Traceback (most recent call last):\n TypeError: Expected Mapping or Sequence, but got <class 'set'>.\n \"\"\"\nif obj is None:\nreturn cls()\nif issubclass(cls, FlatDict):\ncls = cls.empty # type: ignore # pylint: disable=W0642\nif isinstance(obj, Mapping):\nreturn cls(obj)\nif isinstance(obj, Sequence):\ntry:\nreturn cls(obj)\nexcept ValueError:\nreturn [cls(json) for json in obj]\nraise TypeError(f\"Expected Mapping or Sequence, but got {type(obj)}.\")\nfrom_json(file, *args, **kwargs) classmethod","text":"Construct FlatDict from json file.
This method internally calls self.from_jsons() to construct object from json string. You may overwrite from_jsons in case something is not json serializable.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict.from_json('tests/test.json')\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Python@classmethod\ndef from_json(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json file.\n This method internally calls `self.from_jsons()` to construct object from json string.\n You may overwrite `from_jsons` in case something is not json serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict.from_json('tests/test.json')\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_jsons(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_jsons(fp.read(), *args, **kwargs)\nfrom_jsons(string, *args, **kwargs) classmethod","text":"Construct FlatDict from json string.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\nchanfig/flat_dict.py Python@classmethod\ndef from_jsons(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nreturn cls.from_dict(json_loads(string, *args, **kwargs))\nfrom_yaml(file, *args, **kwargs) classmethod","text":"Construct FlatDict from yaml file.
This method internally calls self.from_yamls() to construct object from yaml string. You may overwrite from_yamls in case something is not yaml serializable.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_yaml('tests/test.yaml').dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Python@classmethod\ndef from_yaml(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml file.\n This method internally calls `self.from_yamls()` to construct object from yaml string.\n You may overwrite `from_yamls` in case something is not yaml serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yaml('tests/test.yaml').dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nkwargs.setdefault(\"Loader\", YamlLoader)\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_yamls(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_dict(yaml_load(fp, *args, **kwargs))\nfrom_yamls(string, *args, **kwargs) classmethod","text":"Construct FlatDict from yaml string.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\nchanfig/flat_dict.py Python@classmethod\ndef from_yamls(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nkwargs.setdefault(\"Loader\", SafeLoader)\nreturn cls.from_dict(yaml_load(string, *args, **kwargs))\nget(name, default=None)","text":"Get value from FlatDict.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If FlatDict does not contain name, return default.
Raises:
Type DescriptionKeyError If FlatDict does not contain name and default is not specified.
TypeError If name is not hashable.
Examples:
Python Console Session>>> d = FlatDict(d=1013)\n>>> d.get('d')\n1013\n>>> d['d']\n1013\n>>> d.d\n1013\n>>> d.get('d', None)\n1013\n>>> d.get('f', 2)\n2\n>>> d.get('f')\n>>> d.get('f', Null)\nTraceback (most recent call last):\nKeyError: 'f'\nchanfig/flat_dict.py Pythondef get(self, name: Any, default: Any = None) -> Any:\nr\"\"\"\n Get value from `FlatDict`.\n Args:\n name:\n default:\n Returns:\n value:\n If `FlatDict` does not contain `name`, return `default`.\n Raises:\n KeyError: If `FlatDict` does not contain `name` and `default` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = FlatDict(d=1013)\n >>> d.get('d')\n 1013\n >>> d['d']\n 1013\n >>> d.d\n 1013\n >>> d.get('d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('f')\n >>> d.get('f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\nif name in self:\nreturn dict.__getitem__(self, name)\nif default is not Null:\nreturn default\nreturn self.__missing__(name)\ngetattr(name, default=Null)","text":"Get attribute of FlatDict.
Note that it won\u2019t retrieve value in FlatDict,
Parameters:
Name Type Description Defaultname str required default Any Null Returns:
Name Type Descriptionvalue Any If FlatDict does not contain name, return default.
Raises:
Type DescriptionAttributeError If FlatDict does not contain name and default is not specified.
Examples:
Python Console Session>>> d = FlatDict(a=1)\n>>> d.get('a')\n1\n>>> d.getattr('a')\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'a'\n>>> d.getattr('b', 2)\n2\n>>> d.setattr('b', 3)\n>>> d.getattr('b')\n3\nchanfig/flat_dict.py Pythondef getattr(self, name: str, default: Any = Null) -> Any:\nr\"\"\"\n Get attribute of `FlatDict`.\n Note that it won't retrieve value in `FlatDict`,\n Args:\n name:\n default:\n Returns:\n value: If `FlatDict` does not contain `name`, return `default`.\n Raises:\n AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.\n Examples:\n >>> d = FlatDict(a=1)\n >>> d.get('a')\n 1\n >>> d.getattr('a')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'a'\n >>> d.getattr('b', 2)\n 2\n >>> d.setattr('b', 3)\n >>> d.getattr('b')\n 3\n \"\"\"\ntry:\nif name in self.__dict__:\nreturn self.__dict__[name]\nif name in self.__class__.__dict__:\nreturn self.__class__.__dict__[name]\nreturn super().getattr(name, default) # type: ignore\nexcept AttributeError:\nif default is not Null:\nreturn default\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ngpu()","text":"Move all tensors to gpu.
Returns:
Name Type Descriptionself FlatDict Alias:
cudaExamples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.gpu().dict()\n{'a': tensor(1, device='cuda:0')}\n>>> d.cuda().dict() # alias\n{'a': tensor(1, device='cuda:0')}\nchanfig/flat_dict.py Pythondef gpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to gpu.\n Returns:\n self:\n **Alias**:\n + `cuda`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.gpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n >>> d.cuda().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"cuda\"))\nhasattr(name)","text":"Determine if an attribute exists in FlatDict.
Parameters:
Name Type Description Defaultname str required Returns:
Type Descriptionbool Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('name', 'chang')\n>>> d.hasattr('name')\nTrue\n>>> d.delattr('name')\n>>> d.hasattr('name')\nFalse\nchanfig/flat_dict.py Pythondef hasattr(self, name: str) -> bool:\nr\"\"\"\n Determine if an attribute exists in `FlatDict`.\n Args:\n name:\n Returns:\n (bool):\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.hasattr('name')\n True\n >>> d.delattr('name')\n >>> d.hasattr('name')\n False\n \"\"\"\ntry:\nif name in self.__dict__ or name in self.__class__.__dict__:\nreturn True\nreturn super().hasattr(name) # type: ignore\nexcept AttributeError:\nreturn False\ninter(other, *args, **kwargs)","text":"Alias of intersect.
chanfig/flat_dict.py Pythondef inter(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`intersect`][chanfig.FlatDict.intersect].\n \"\"\"\nreturn self.intersect(other, *args, **kwargs)\ninterpolate(use_variable=True, interpolators=None)","text":"Perform Variable interpolation.
Variable interpolation allows you to set the value of one key to be the value of another key easily.
Parameters:
Name Type Description Defaultuse_variable bool Whether to convert values to Variable objects.
True interpolators MutableMapping | None Mapping contains values for interpolation. Defaults to self.
None Raises:
Type DescriptionValueError If value is not interpolatable.
ValueError If reference to itself.
ValueError If has circular reference.
See Also[Variable][chanfig.Variable]: Mutable wrapper of immutable objects.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n>>> d.dict()\n{'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n>>> d.interpolate().dict()\n{'a': 1, 'b': 1, 'c': '1.1'}\n>>> isinstance(d.a, Variable)\nTrue\n>>> d.a += 1\n>>> d.dict()\n{'a': 2, 'b': 2, 'c': '1.1'}\n>>> d.a is d.b\nTrue\n>>> d.b is d.c\nFalse\n>>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n>>> d.dict()\n{'a': 1, 'b': '${a}', 'c': '${b}'}\n>>> d.interpolate(False).dict()\n{'a': 1, 'b': 1, 'c': 1}\n>>> isinstance(d.a, Variable)\nFalse\n>>> d.a += 1\n>>> d.dict()\n{'a': 2, 'b': 1, 'c': 1}\n>>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: Cannot interpolate b to itself.\n>>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: Circular reference found: a->b->c->d->a.\n>>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n).\nchanfig/flat_dict.py Pythondef interpolate(self, use_variable: bool = True, interpolators: MutableMapping | None = None) -> FlatDict:\nr\"\"\"\n Perform Variable interpolation.\n Variable interpolation allows you to set the value of one key to be the value of another key easily.\n Args:\n use_variable: Whether to convert values to `Variable` objects.\n interpolators: Mapping contains values for interpolation. Defaults to `self`.\n Raises:\n ValueError: If value is not interpolatable.\n ValueError: If reference to itself.\n ValueError: If has circular reference.\n See Also:\n [Variable][`chanfig.Variable`]: Mutable wrapper of immutable objects.\n Examples:\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n >>> d.interpolate().dict()\n {'a': 1, 'b': 1, 'c': '1.1'}\n >>> isinstance(d.a, Variable)\n True\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 2, 'c': '1.1'}\n >>> d.a is d.b\n True\n >>> d.b is d.c\n False\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${b}'}\n >>> d.interpolate(False).dict()\n {'a': 1, 'b': 1, 'c': 1}\n >>> isinstance(d.a, Variable)\n False\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 1, 'c': 1}\n >>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Cannot interpolate b to itself.\n >>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Circular reference found: a->b->c->d->a.\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n ).\n \"\"\"\ninterpolators = interpolators or self\nplaceholders: dict[str, list[str]] = {}\nfor key, value in self.all_items():\nif isinstance(value, list):\nfor v in value:\nself.find_placeholders(key, v, placeholders)\nelif isinstance(value, Mapping):\nfor v in value.values():\nself.find_placeholders(key, v, placeholders)\nelse:\nself.find_placeholders(key, value, placeholders)\ncircular_references = find_circular_reference(placeholders)\nif circular_references:\nraise ValueError(f\"Circular reference found: {'->'.join(circular_references)}.\")\nif use_variable:\nplaceholder_names = {i for j in placeholders.values() for i in j}\nfor name in list(placeholder_names.difference(placeholders.keys())):\nif name not in interpolators:\nraise ValueError(f\"{name} is not found in {interpolators}.\")\nif not isinstance(interpolators[name], Variable):\ninterpolators[name] = Variable(interpolators[name])\nfor key, value in placeholders.items():\nif isinstance(self[key], list):\nfor index, v in enumerate(self[key]):\nself[key][index] = self.substitute(v, interpolators, value)\nelif isinstance(self[key], Mapping):\nfor k, v in self[key].items():\nself[key][k] = self.substitute(v, interpolators, value)\nelse:\nself[key] = self.substitute(self[key], interpolators, value)\nreturn self\nintersect(other)","text":"Intersection of FlatDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required Returns:
Type DescriptionFlatDict Alias:
interExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.intersect(n).dict()\n{}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.intersect(l).dict()\n{'c': 3}\n>>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d.intersect(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n>>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n{}\nchanfig/flat_dict.py Pythondef intersect(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Intersection of `FlatDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n Returns:\n (FlatDict):\n **Alias**:\n + `inter`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.intersect(n).dict()\n {}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.intersect(l).dict()\n {'c': 3}\n >>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n {}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(**{key: value for key, value in other if key in self and self[key] == value}) # type: ignore\njson(file, *args, **kwargs)","text":"Dump FlatDict to json file.
This method internally calls self.jsons() to generate json string. You may overwrite jsons in case something is not json serializable.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.json(\"tests/test.json\")\nchanfig/flat_dict.py Pythondef json(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to json file.\n This method internally calls `self.jsons()` to generate json string.\n You may overwrite `jsons` in case something is not json serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.json(\"tests/test.json\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(self.jsons(*args, **kwargs))\njsons(*args, **kwargs)","text":"Dump FlatDict to json string.
Returns:
Type Descriptionstr Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.jsons()\n'{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\nchanfig/flat_dict.py Pythondef jsons(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to json string.\n Returns:\n (str):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.jsons()\n '{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\n \"\"\"\nkwargs.setdefault(\"cls\", JsonEncoder)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn json_dumps(self.dict(), *args, **kwargs)\nload(file, method=None, *args, **kwargs) classmethod","text":"Load FlatDict from file.
Parameters:
Name Type Description Defaultfile File File to load from.
requiredmethod str | None File type, should be in JSON or YAML.
None Returns:
Type DescriptionFlatDict Raises:
Type DescriptionValueError If load from IO and method is not specified.
TypeError If dump to unsupported extension.
Examples:
Python Console Session>>> d = FlatDict.load(\"tests/test.yaml\")\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d.load(\"tests/test.conf\")\nTraceback (most recent call last):\nTypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"tests/test.yaml\") as f:\n... d.load(f)\nTraceback (most recent call last):\nValueError: `method` must be specified when loading from IO.\nchanfig/flat_dict.py Python@classmethod\ndef load( # pylint: disable=W1113\ncls, file: File, method: str | None = None, *args: Any, **kwargs: Any\n) -> FlatDict:\n\"\"\"\n Load `FlatDict` from file.\n Args:\n file: File to load from.\n method: File type, should be in `JSON` or `YAML`.\n Returns:\n (FlatDict):\n Raises:\n ValueError: If load from `IO` and `method` is not specified.\n TypeError: If dump to unsupported extension.\n Examples:\n >>> d = FlatDict.load(\"tests/test.yaml\")\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.load(\"tests/test.conf\")\n Traceback (most recent call last):\n TypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"tests/test.yaml\") as f:\n ... d.load(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when loading from IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when loading from IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in JSON:\nreturn cls.from_json(file, *args, **kwargs)\nif extension in YAML:\nreturn cls.from_yaml(file, *args, **kwargs)\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\nmerge(*args, overwrite=True, **kwargs)","text":"Merge other into FlatDict.
Parameters:
Name Type Description Default*args Any Mapping or Sequence to be merged.
() overwrite bool Whether to overwrite existing values.
True **kwargs Any Mapping to be merged.
{} Returns:
Name Type Descriptionself FlatDict Alias:
unionExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.merge(n).dict()\n{'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.merge(l).dict()\n{'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n>>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n{'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d = FlatDict()\n>>> d.merge({1: 1, 2: 2, 3:3}).dict()\n{1: 1, 2: 2, 3: 3}\n>>> d.merge(d.clone()).dict()\n{1: 1, 2: 2, 3: 3}\n>>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n{1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\nchanfig/flat_dict.py Pythondef merge(self, *args: Any, overwrite: bool = True, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge `other` into `FlatDict`.\n Args:\n *args: `Mapping` or `Sequence` to be merged.\n overwrite: Whether to overwrite existing values.\n **kwargs: `Mapping` to be merged.\n Returns:\n self:\n **Alias**:\n + `union`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.merge(n).dict()\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.merge(l).dict()\n {'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n >>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d = FlatDict()\n >>> d.merge({1: 1, 2: 2, 3:3}).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge(d.clone()).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n {1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\n \"\"\"\nif len(args) == 1:\nargs = args[0]\nif isinstance(args, (PathLike, str, bytes)):\nargs = self.load(args) # type: ignore\nwarn(\n\"merge file is deprecated and maybe removed in a future release. Use `merge_from_file` instead.\",\nPendingDeprecationWarning,\n)\nself._merge(self, args, overwrite=overwrite)\nelif len(args) > 1:\nself._merge(self, args, overwrite=overwrite)\nif kwargs:\nself._merge(self, kwargs, overwrite=overwrite)\nreturn self\nmerge_from_file(file, *args, **kwargs)","text":"Merge content of file into FlatDict.
Parameters:
Name Type Description Defaultfile File required *args Any Passed to load.
() **kwargs Any Passed to load.
{} Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=1)\n>>> d.merge_from_file(\"tests/test.yaml\").dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Pythondef merge_from_file(self, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge content of `file` into `FlatDict`.\n Args:\n file (File):\n *args: Passed to [`load`][chanfig.FlatDict.load].\n **kwargs: Passed to [`load`][chanfig.FlatDict.load].\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=1)\n >>> d.merge_from_file(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn self.merge(self.load(file, *args, **kwargs))\nopen(file, *args, encoding='utf-8', **kwargs) staticmethod","text":"Open file IO from file path or IO.
This methods extends the ability of built-in open by allowing it to accept an IOBase object.
Parameters:
Name Type Description Defaultfile File File path or IO.
required*args Any Additional arguments passed to open. Defaults to ().
() **kwargs Any Any Additional keyword arguments passed to open. Defaults to {}.
{} Yields:
Type DescriptionGenerator[IOBase | IO, Any, Any] Examples:
Python Console Session>>> with FlatDict.open(\"tests/test.yaml\") as fp:\n... print(fp.read())\na: 1\nb: 2\nc: 3\n>>> io = open(\"tests/test.yaml\")\n>>> with FlatDict.open(io) as fp:\n... print(fp.read())\na: 1\nb: 2\nc: 3\n>>> with FlatDict.open(123, mode=\"w\") as fp:\n... print(fp.read())\nTraceback (most recent call last):\nTypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\nchanfig/flat_dict.py Python@staticmethod\n@contextmanager\ndef open(file: File, *args: Any, encoding: str = \"utf-8\", **kwargs: Any) -> Generator[IOBase | IO, Any, Any]:\nr\"\"\"\n Open file IO from file path or IO.\n This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.\n Args:\n file: File path or IO.\n *args: Additional arguments passed to `open`.\n Defaults to ().\n **kwargs: Any\n Additional keyword arguments passed to `open`.\n Defaults to {}.\n Yields:\n (Generator[IOBase | IO, Any, Any]):\n Examples:\n >>> with FlatDict.open(\"tests/test.yaml\") as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> io = open(\"tests/test.yaml\")\n >>> with FlatDict.open(io) as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> with FlatDict.open(123, mode=\"w\") as fp:\n ... print(fp.read())\n Traceback (most recent call last):\n TypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\n \"\"\"\nif isinstance(file, (IOBase, IO)):\nyield file\nelif isinstance(file, (PathLike, str, bytes)):\ntry:\nfile = open(file, *args, encoding=encoding, **kwargs) # type: ignore # noqa: SIM115\nyield file # type: ignore\nfinally:\nwith suppress(Exception):\nfile.close() # type: ignore\nelse:\nraise TypeError(f\"expected str, bytes, os.PathLike, IO or IOBase, not {type(file).__name__}\")\nsave(file, method=None, *args, **kwargs)","text":"Save FlatDict to file.
Raises:
Type DescriptionValueError If save to IO and method is not specified.
TypeError If save to unsupported extension.
Alias:
saveExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.save(\"tests/test.yaml\")\n>>> d.save(\"test.conf\")\nTraceback (most recent call last):\nTypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"test.yaml\", \"w\") as f:\n... d.save(f)\nTraceback (most recent call last):\nValueError: `method` must be specified when saving to IO.\nchanfig/flat_dict.py Pythondef save(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.save(\"tests/test.yaml\")\n >>> d.save(\"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... d.save(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nreturn self.yaml(file=file, *args, **kwargs) # type: ignore\nif extension in JSON:\nreturn self.json(file=file, *args, **kwargs) # type: ignore\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\nset(name, value)","text":"Set value of FlatDict.
Parameters:
Name Type Description Defaultname Any required value Any required Examples:
Python Console Session>>> d = FlatDict()\n>>> d.set('d', 1013)\n>>> d.get('d')\n1013\n>>> d['n'] = 'chang'\n>>> d.n\n'chang'\n>>> d.n = 'liu'\n>>> d['n']\n'liu'\nchanfig/flat_dict.py Pythondef set(self, name: Any, value: Any) -> None:\nr\"\"\"\n Set value of `FlatDict`.\n Args:\n name:\n value:\n Examples:\n >>> d = FlatDict()\n >>> d.set('d', 1013)\n >>> d.get('d')\n 1013\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n \"\"\"\nif name in self and isinstance(self.get(name), Variable):\nself.get(name).set(value)\nelse:\ndict.__setitem__(self, name, value)\nsetattr(name, value)","text":"Set attribute of FlatDict.
Note that it won\u2019t alter values in FlatDict.
Parameters:
Name Type Description Defaultname str required value Any required Warns:
Type DescriptionRuntimeWarning If name already exists in FlatDict.
Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('attr', 'value')\n>>> d.getattr('attr')\n'value'\n>>> d.set('d', 1013)\n>>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n>>> d.get('d')\n1013\n>>> d.d\n1013\n>>> d.getattr('d')\n1031\nchanfig/flat_dict.py Pythondef setattr(self, name: str, value: Any) -> None:\nr\"\"\"\n Set attribute of `FlatDict`.\n Note that it won't alter values in `FlatDict`.\n Args:\n name:\n value:\n Warns:\n RuntimeWarning: If name already exists in `FlatDict`.\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('attr', 'value')\n >>> d.getattr('attr')\n 'value'\n >>> d.set('d', 1013)\n >>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n >>> d.get('d')\n 1013\n >>> d.d\n 1013\n >>> d.getattr('d')\n 1031\n \"\"\"\nif name in self:\nwarn(\nf\"{name} already exists in {self.__class__.__name__}.\\n\"\nf\"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.\",\nRuntimeWarning,\n)\nself.__dict__[name] = value\nsort(key=None, reverse=False)","text":"Sort FlatDict.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.sort().dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d = FlatDict(b=2, c=3, a=1)\n>>> d.sort().dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> a = [1]\n>>> d = FlatDict(z=0, a=a)\n>>> a.append(2)\n>>> d.sort().dict()\n{'a': [1, 2], 'z': 0}\nchanfig/flat_dict.py Pythondef sort(self, key: Callable | None = None, reverse: bool = False) -> FlatDict:\nr\"\"\"\n Sort `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d = FlatDict(b=2, c=3, a=1)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> a = [1]\n >>> d = FlatDict(z=0, a=a)\n >>> a.append(2)\n >>> d.sort().dict()\n {'a': [1, 2], 'z': 0}\n \"\"\"\nitems = sorted(self.items(), key=key, reverse=reverse)\nself.clear()\nfor k, v in items:\nself[k] = v\nreturn self\nto(cls)","text":"Convert values of FlatDict to target cls.
Parameters:
Name Type Description Defaultcls str | device | dtype required Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.to(int)\nTraceback (most recent call last):\nTypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\nchanfig/flat_dict.py Pythondef to(self, cls: str | TorchDevice | TorchDType) -> FlatDict: # pragma: no cover\nr\"\"\"\n Convert values of `FlatDict` to target `cls`.\n Args:\n cls (str | torch.device | torch.dtype):\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.to(int)\n Traceback (most recent call last):\n TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\n \"\"\"\n# pylint: disable=C0103\nif isinstance(cls, (str, TorchDevice, TorchDType)):\nfor k, v in self.all_items():\nif hasattr(v, \"to\"):\nself[k] = v.to(cls)\nreturn self\nraise TypeError(f\"to() only support torch.dtype and torch.device, but got {cls}.\")\ntpu()","text":"Move all tensors to tpu.
Returns:
Name Type Descriptionself FlatDict Alias:
xlaExamples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.tpu().dict()\n{'a': tensor(1, device='xla:0')}\n>>> d.xla().dict() # alias\n{'a': tensor(1, device='xla:0')}\nchanfig/flat_dict.py Pythondef tpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to tpu.\n Returns:\n self:\n **Alias**:\n + `xla`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.tpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n >>> d.xla().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"xla\"))\nunion(*args, **kwargs)","text":"Alias of merge.
chanfig/flat_dict.py Pythondef union(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`merge`][chanfig.FlatDict.merge].\n \"\"\"\nreturn self.merge(*args, **kwargs)\nvalidate()","text":"Validate FlatDict.
Raises:
Type DescriptionTypeError If value is not of the type declared in class annotations.
TypeError If Variable has invalid type.
ValueError If Variable has invalid value.
Examples:
Python Console Session>>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n>>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\nTraceback (most recent call last):\nTypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n>>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\nTraceback (most recent call last):\nValueError: 'n' has invalid value. Value chang is not valid.\nchanfig/flat_dict.py Pythondef validate(self) -> None:\nr\"\"\"\n Validate `FlatDict`.\n Raises:\n TypeError: If value is not of the type declared in class annotations.\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n >>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\n Traceback (most recent call last):\n ValueError: 'n' has invalid value. Value chang is not valid.\n \"\"\"\nself._validate(self)\nxla()","text":"Alias of tpu.
chanfig/flat_dict.py Pythondef xla(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`tpu`][chanfig.FlatDict.tpu].\n \"\"\"\nreturn self.tpu()\nyaml(file, *args, **kwargs)","text":"Dump FlatDict to yaml file.
This method internally calls self.yamls() to generate yaml string. You may overwrite yamls in case something is not yaml serializable.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.yaml(\"tests/test.yaml\")\nchanfig/flat_dict.py Pythondef yaml(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to yaml file.\n This method internally calls `self.yamls()` to generate yaml string.\n You may overwrite `yamls` in case something is not yaml serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.yaml(\"tests/test.yaml\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nself.yamls(fp, *args, **kwargs)\nyamls(*args, **kwargs)","text":"Dump FlatDict to yaml string.
Returns:
Type Descriptionstr Examples:
Python Console Session>>> FlatDict(a=1, b=2, c=3).yamls()\n'a: 1\\nb: 2\\nc: 3\\n'\nchanfig/flat_dict.py Pythondef yamls(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to yaml string.\n Returns:\n (str):\n Examples:\n >>> FlatDict(a=1, b=2, c=3).yamls()\n 'a: 1\\nb: 2\\nc: 3\\n'\n \"\"\"\nkwargs.setdefault(\"Dumper\", YamlDumper)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn yaml_dump(self.dict(), *args, **kwargs) # type: ignore\nConvert an object to a dict.
Note that when converting a set object, it may be converted to a tuple object if its values is not hashable.
Parameters:
Name Type Description Defaultobj Any Object to be converted.
requiredReturns:
Type DescriptionMapping[str, Any] A dict.
Examples:
Python Console Session>>> to_dict(1)\n1\n>>> to_dict([1, 2, 3])\n[1, 2, 3]\n>>> to_dict((1, 2, 3))\n(1, 2, 3)\n>>> to_dict({1, 2, 3})\n{1, 2, 3}\n>>> to_dict({'a': 1, 'b': 2})\n{'a': 1, 'b': 2}\n>>> to_dict(Variable(1))\n1\n>>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))\n{'a': [[[[[{'b': 1}]]]]]}\n>>> to_dict(FlatDict(a={FlatDict(b=1)}))\n{'a': ({'b': 1},)}\nchanfig/flat_dict.py Pythondef to_dict(obj: Any) -> Mapping[str, Any]: # pylint: disable=R0911\nr\"\"\"\n Convert an object to a dict.\n Note that when converting a `set` object, it may be converted to a `tuple` object if its values is not hashable.\n Args:\n obj: Object to be converted.\n Returns:\n A dict.\n Examples:\n >>> to_dict(1)\n 1\n >>> to_dict([1, 2, 3])\n [1, 2, 3]\n >>> to_dict((1, 2, 3))\n (1, 2, 3)\n >>> to_dict({1, 2, 3})\n {1, 2, 3}\n >>> to_dict({'a': 1, 'b': 2})\n {'a': 1, 'b': 2}\n >>> to_dict(Variable(1))\n 1\n >>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))\n {'a': [[[[[{'b': 1}]]]]]}\n >>> to_dict(FlatDict(a={FlatDict(b=1)}))\n {'a': ({'b': 1},)}\n \"\"\"\nif isinstance(obj, Mapping):\nreturn {k: to_dict(v) for k, v in obj.items()}\nif isinstance(obj, list):\nreturn [to_dict(v) for v in obj] # type: ignore\nif isinstance(obj, tuple):\nreturn tuple(to_dict(v) for v in obj) # type: ignore\nif isinstance(obj, set):\ntry:\nreturn {to_dict(v) for v in obj} # type: ignore\nexcept TypeError:\nreturn tuple(to_dict(v) for v in obj) # type: ignore\nif isinstance(obj, Variable):\nreturn obj.value\nreturn obj\noptions: heading_level: 0
Save FlatDict to file.
Raises:
Type DescriptionValueError If save to IO and method is not specified.
TypeError If save to unsupported extension.
Alias:
saveExamples:
Python Console Session>>> obj = {\"a\": 1, \"b\": 2, \"c\": 3}\n>>> save(obj, \"test.yaml\")\n>>> save(obj, \"test.json\")\n>>> save(obj, \"test.conf\")\nTraceback (most recent call last):\nTypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"test.yaml\", \"w\") as f:\n... save(obj, f)\nTraceback (most recent call last):\nValueError: `method` must be specified when saving to IO.\nchanfig/functional.py Pythondef save(obj, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> obj = {\"a\": 1, \"b\": 2, \"c\": 3}\n >>> save(obj, \"test.yaml\")\n >>> save(obj, \"test.json\")\n >>> save(obj, \"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... save(obj, f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif isinstance(obj, FlatDict):\nreturn obj.save(file, method, *args, **kwargs)\ndata = to_dict(obj)\nif method is None:\nif isinstance(file, IOBase):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nwith FlatDict.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nyaml_dump(data, fp, *args, **kwargs)\nreturn\nif extension in JSON:\nwith FlatDict.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(json_dumps(data, *args, **kwargs))\nreturn\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\") # type: ignore\noptions: heading_level: 0
Load a file into a NestedDict.
This function simply calls NestedDict.load.
Parameters:
Name Type Description Defaultfile PathStr The file to load.
required*args Any The arguments to pass to NestedDict.load.
() **kwargs Any The keyword arguments to pass to NestedDict.load.
{} See Also load
Examples:
Python Console Session>>> from chanfig import load\n>>> config = load(\"tests/test.yaml\")\n>>> config\nNestedDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\nchanfig/functional.py Pythondef load(file: PathStr, cls: type = NestedDict, *args: Any, **kwargs: Any) -> NestedDict: # pylint: disable=W1113\nr\"\"\"\n Load a file into a `NestedDict`.\n This function simply calls `NestedDict.load`.\n Args:\n file: The file to load.\n *args: The arguments to pass to `NestedDict.load`.\n **kwargs: The keyword arguments to pass to `NestedDict.load`.\n See Also:\n [`load`][chanfig.FlatDict.load]\n Examples:\n >>> from chanfig import load\n >>> config = load(\"tests/test.yaml\")\n >>> config\n NestedDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n \"\"\"\nreturn cls.load(file, *args, **kwargs) # type: ignore\noptions: heading_level: 0
Apply func to all children of obj.
Note that this method is meant for non-in-place modification of obj and should return the original object.
Parameters:
Name Type Description Defaultobj Any Object to apply function.
requiredfunc Callable Function to be applied.
required*args Any Positional arguments to be passed to func.
() **kwargs Any Keyword arguments to be passed to func.
{} Returns:
Type DescriptionAny Return value of func.
apply_: Apply an in-place operation.
chanfig/nested_dict.py Pythondef apply(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Apply `func` to all children of `obj`.\n Note that this method is meant for non-in-place modification of `obj` and should return the original object.\n Args:\n obj: Object to apply function.\n func: Function to be applied.\n *args: Positional arguments to be passed to `func`.\n **kwargs: Keyword arguments to be passed to `func`.\n Returns:\n (Any): Return value of `func`.\n See Also:\n [`apply_`][chanfig.nested_dict.apply_]: Apply an in-place operation.\n \"\"\"\nif isinstance(obj, NestedDict):\nreturn obj.empty_like(**{k: apply(v, func, *args, **kwargs) for k, v in obj.items()})\nif isinstance(obj, Mapping):\nreturn {k: apply(v, func, *args, **kwargs) for k, v in obj.items()}\nif isinstance(obj, list):\nreturn [apply(v, func, *args, **kwargs) for v in obj]\nif isinstance(obj, tuple):\nreturn tuple(apply(v, func, *args, **kwargs) for v in obj)\nif isinstance(obj, set):\ntry:\nreturn {apply(v, func, *args, **kwargs) for v in obj}\nexcept TypeError:\ntuple(apply(v, func, *args, **kwargs) for v in obj)\nreturn func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)\noptions: heading_level: 0
Apply func to all children of obj.
Note that this method is meant for non-in-place modification of obj and should return a new object.
Parameters:
Name Type Description Defaultobj Any Object to apply function.
requiredfunc Callable Function to be applied.
required*args Any Positional arguments to be passed to func.
() **kwargs Any Keyword arguments to be passed to func.
{} Returns:
Type DescriptionAny Return value of func.
apply_: Apply a non-in-place operation.
chanfig/nested_dict.py Pythondef apply_(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Apply `func` to all children of `obj`.\n Note that this method is meant for non-in-place modification of `obj` and should return a new object.\n Args:\n obj: Object to apply function.\n func: Function to be applied.\n *args: Positional arguments to be passed to `func`.\n **kwargs: Keyword arguments to be passed to `func`.\n Returns:\n (Any): Return value of `func`.\n See Also:\n [`apply_`][chanfig.nested_dict.apply]: Apply a non-in-place operation.\n \"\"\"\nif isinstance(obj, Mapping):\nfor v in obj.values():\napply_(v, func, *args, **kwargs)\nif isinstance(obj, (list, tuple, set)):\nfor v in obj:\napply_(v, func, *args, **kwargs)\nreturn func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)\noptions: heading_level: 0
"},{"location":"nested_dict/","title":"NestedDict","text":" Bases: DefaultDict
NestedDict further extends DefaultDict object by introducing a nested structure with delimiter. By default, delimiter is ., but it could be modified in subclass or by calling dict.setattr('delimiter', D).
d = NestedDict({\"a.b.c\": 1}) is equivalent to d = NestedDict({\"a\": {\"b\": {\"c\": 1}}}), and you can access members either by d[\"a.b.c\"] or more simply by d.a.b.c.
This behaviour allows you to pass keyword arguments to other functions as easy as func1(**d.func1).
Since NestedDict inherits from DefaultDict, it also supports default_factory. With default_factory, you can assign d.a.b.c = 1 without assign d.a = NestedDict() in the first place. Note that the constructor of NestedDict is different from DefaultDict, default_factory is not a positional argument, and must be set in a keyword argument.
NestedDict also introduce all_keys, all_values, all_items methods to get all keys, values, items respectively in the nested structure.
Attributes:
Name Type Descriptionconvert_mapping bool bool = False If True, all new values with type of Mapping will be converted to default_factory. If default_factory is Null, will create an empty instance via self.empty as default_factory.
delimiter str str = \u201c.\u201d Delimiter for nested structure.
NotesWhen convert_mapping specified, all new values with type of Mapping will be converted to default_factory. If default_factory is Null, will create an empty instance via self.empty as default_factory.
convert_mapping is automatically applied to arguments during initialisation.
Examples:
Python Console Session>>> NestedDict({\"f.n\": \"chang\"})\nNestedDict(\n ('f'): NestedDict(\n ('n'): 'chang'\n )\n)\n>>> d = NestedDict({\"f.n\": \"chang\"}, default_factory=NestedDict)\n>>> d.i.d = 1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}}\nchanfig/nested_dict.py Pythonclass NestedDict(DefaultDict): # type: ignore # pylint: disable=E1136\nr\"\"\"\n `NestedDict` further extends `DefaultDict` object by introducing a nested structure with `delimiter`.\n By default, `delimiter` is `.`, but it could be modified in subclass or by calling `dict.setattr('delimiter', D)`.\n `d = NestedDict({\"a.b.c\": 1})` is equivalent to `d = NestedDict({\"a\": {\"b\": {\"c\": 1}}})`,\n and you can access members either by `d[\"a.b.c\"]` or more simply by `d.a.b.c`.\n This behaviour allows you to pass keyword arguments to other functions as easy as `func1(**d.func1)`.\n Since `NestedDict` inherits from `DefaultDict`, it also supports `default_factory`.\n With `default_factory`, you can assign `d.a.b.c = 1` without assign `d.a = NestedDict()` in the first place.\n Note that the constructor of `NestedDict` is different from `DefaultDict`, `default_factory` is not a positional\n argument, and must be set in a keyword argument.\n `NestedDict` also introduce `all_keys`, `all_values`, `all_items` methods to get all keys, values, items\n respectively in the nested structure.\n Attributes:\n convert_mapping: bool = False\n If `True`, all new values with type of `Mapping` will be converted to `default_factory`.\n If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.\n delimiter: str = \".\"\n Delimiter for nested structure.\n Notes:\n When `convert_mapping` specified, all new values with type of `Mapping` will be converted to `default_factory`.\n If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.\n `convert_mapping` is automatically applied to arguments during initialisation.\n Examples:\n >>> NestedDict({\"f.n\": \"chang\"})\n NestedDict(\n ('f'): NestedDict(\n ('n'): 'chang'\n )\n )\n >>> d = NestedDict({\"f.n\": \"chang\"}, default_factory=NestedDict)\n >>> d.i.d = 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}}\n \"\"\"\nconvert_mapping: bool = False\ndelimiter: str = \".\"\nfallback: bool = False\ndef __init__(\nself,\n*args: Any,\ndefault_factory: Callable | None = None,\nconvert_mapping: bool | None = None,\nfallback: bool | None = None,\n**kwargs: Any,\n) -> None:\nsuper().__init__(default_factory)\nself.merge(*args, **kwargs)\nif convert_mapping is not None:\nself.setattr(\"convert_mapping\", convert_mapping)\nif fallback is not None:\nself.setattr(\"fallback\", fallback)\ndef all_keys(self) -> Generator:\nr\"\"\"\n Get all keys of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_keys())\n ['a', 'b.c', 'b.d']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_keys)\ndef all_keys(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_keys(value, key)\nelse:\nyield key\nreturn all_keys(self)\ndef all_values(self) -> Generator:\nr\"\"\"\n Get all values of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_values())\n [1, 2, 3]\n \"\"\"\nfor value in self.values():\nif isinstance(value, NestedDict):\nyield from value.all_values()\nelse:\nyield value\ndef all_items(self) -> Generator:\nr\"\"\"\n Get all items of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_items())\n [('a', 1), ('b.c', 2), ('b.d', 3)]\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_items)\ndef all_items(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_items(value, key)\nelse:\nyield key, value\nreturn all_items(self)\ndef apply(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for non-in-place modification of `obj`, for example, [`to`][chanfig.NestedDict.to].\n Args:\n func (Callable):\n See Also:\n [`apply_`][chanfig.NestedDict.apply_]: Apply an in-place operation.\n [`apply`][chanfig.nested_dict.apply]: Implementation of `apply`.\n tionples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply(func).dict()\n {'a': {}, 'b': [{}], 'c': ({},), 'd': ({},)}\n \"\"\"\nreturn apply(self, func, *args, **kwargs)\ndef apply_(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for in-place modification of `obj`, for example, [`freeze`][chanfig.Config.freeze].\n Args:\n func (Callable):\n See Also:\n [`apply`][chanfig.NestedDict.apply]: Apply a non-in-place operation.\n [`apply_`][chanfig.nested_dict.apply_]: Implementation of `apply_` method.\n Examples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply_(func).dict()\n {'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\n \"\"\"\napply_(self, func, *args, **kwargs)\nreturn self\ndef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `NestedDict`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `NestedDict` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('i.d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('a.b', None)\n >>> d.f\n NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n >>> del d.f\n >>> d = NestedDict({\"i.d\": 1013})\n >>> d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> d.e = {}\n >>> d.get('e.f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n >>> d.get('e.f')\n >>> d.get('e.f', 1)\n 1\n >>> d.e.f\n Traceback (most recent call last):\n AttributeError: 'dict' object has no attribute 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\nif fallback is None:\nfallback = self.getattr(\"fallback\", False)\nfallback_name = name.split(delimiter)[-1] if isinstance(name, str) else name\nfallback_values = []\ntry:\nwhile isinstance(name, str) and delimiter in name:\nif fallback and fallback_name in self:\nfallback_values.append(self.get(fallback_name))\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (KeyError, AttributeError, TypeError):\nif fallback and fallback_values:\nreturn fallback_values[-1]\nif default is not Null:\nreturn default\nraise KeyError(name) from None\nif (fallback and fallback_values) and (not isinstance(self, Iterable) or name not in self):\nreturn fallback_values[-1]\n# if value is a python dict\nif not isinstance(self, NestedDict):\nif name not in self and default is not Null:\nreturn default\nreturn self[name]\nreturn super().get(name, default)\ndef set( # pylint: disable=W0221\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `NestedDict`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Examples:\n >>> d = NestedDict(default_factory=NestedDict)\n >>> d.set('i.d', 1013)\n >>> d.get('i.d')\n 1013\n >>> d.dict()\n {'i': {'d': 1013}}\n >>> d['f.n'] = 'chang'\n >>> d.f.n\n 'chang'\n >>> d.n.l = 'liu'\n >>> d['n.l']\n 'liu'\n >>> d['f.n.e'] = \"error\"\n Traceback (most recent call last):\n ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n >>> d['f.n.e.a'] = \"error\"\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.f.n.e.a = \"error\"\n Traceback (most recent call last):\n AttributeError: 'str' object has no attribute 'e'\n >>> d.setattr('convert_mapping', True)\n >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.a.b.c.d\n 1\n >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.c.d['e.f']\n 2\n >>> d.setattr('convert_mapping', False)\n >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n >>> d['e.f']['c.d']\n 1\n \"\"\"\n# pylint: disable=W0642\nfull_name = name\ndelimiter = self.getattr(\"delimiter\", \".\")\nif convert_mapping is None:\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ndefault_factory = self.getattr(\"default_factory\", self.empty)\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif name in dir(self) and isinstance(getattr(self.__class__, name), (property, cached_property)):\nself, name = getattr(self, name), rest\nelif name not in self and isinstance(self, Mapping):\ndefault = (\nself.__missing__(name, default_factory()) if hasattr(self, \"__missing__\") else default_factory()\n)\nself, name = default, rest\nelse:\nself, name = self[name], rest\nif isinstance(self, NestedDict):\ndefault_factory = self.getattr(\"default_factory\", self.empty)\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif (\nconvert_mapping\nand isinstance(value, Mapping)\nand not isinstance(value, default_factory if isinstance(default_factory, type) else type(self))\nand not isinstance(value, Variable)\n):\ntry:\nvalue = default_factory(**value)\nexcept TypeError:\nvalue = default_factory(value)\nif isinstance(self, NestedDict):\nsuper().set(name, value)\nelif isinstance(self, Mapping):\ndict.__setitem__(self, name, value)\nelse:\nraise ValueError(\nf\"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`.\"\n)\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `NestedDict`.\n Args:\n name:\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> d.dict()\n {'i': {}, 'f': {'n': 'chang'}}\n >>> d.i.d\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'd'\n >>> del d.f.n\n >>> d.dict()\n {'i': {}, 'f': {}}\n >>> d.f.n\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'n'\n >>> del d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> del d['f.n']\n Traceback (most recent call last):\n KeyError: 'n'\n >>> d.e = {'a': {'b': 1}}\n >>> del d['e.a.b']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\n# if value is a python dict\nif not isinstance(self, NestedDict):\ndel self[name]\nreturn\nsuper().delete(name)\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `NestedDict`.\n Args:\n name:\n default:\n Returns:\n value: If `NestedDict` does not contain `name`, return `default`.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n >>> d.pop('i.d')\n 1013\n >>> d.pop('i.d', True)\n True\n >>> d.pop('i.d')\n Traceback (most recent call last):\n KeyError: 'd'\n >>> d.pop('e')\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.pop('e.f')\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif not isinstance(self, dict) or name not in self:\nif default is not Null:\nreturn default\nraise KeyError(name)\nreturn super().pop(name)\ndef validate(self) -> None:\nr\"\"\"\n Validate `NestedDict`.\n Raises:\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n >>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n ValueError: 'd' has invalid value. Value -1 is not valid.\n \"\"\"\nself.apply_(self._validate)\ndef sort(self, key: Callable | None = None, reverse: bool = False, recursive: bool = True) -> NestedDict:\nr\"\"\"\n Sort `NestedDict`.\n Args:\n recursive (bool): Whether to apply `sort` recursively.\n Returns:\n (NestedDict):\n Examples:\n >>> l = [1]\n >>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort(recursive=False).dict()\n {'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n >>> l.append(2)\n >>> d.b.e.f\n [1, 2]\n \"\"\"\nif recursive:\nfor value in self.values():\nif isinstance(value, FlatDict):\nvalue.sort(key=key, reverse=reverse)\nreturn super().sort(key=key, reverse=reverse) # type: ignore\n@staticmethod\ndef _merge(this: FlatDict, that: Iterable, overwrite: bool = True) -> Mapping:\nif not that:\nreturn this\nelif isinstance(that, Mapping):\nthat = that.items()\ncontext = this.converting() if isinstance(this, NestedDict) else nullcontext()\nwith context:\nfor key, value in that:\nif key in this and isinstance(this[key], Mapping):\nif isinstance(value, Mapping):\nNestedDict._merge(this[key], value, overwrite)\nelif overwrite:\nif isinstance(this, NestedDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nelif key in dir(this) and isinstance(getattr(this.__class__, key), (property, cached_property)):\ngetattr(this, key).merge(value, overwrite=overwrite)\nelif overwrite or key not in this:\nif isinstance(this, NestedDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nreturn this\ndef intersect( # pylint: disable=W0221\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Intersection of `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.intersect(n).dict()\n {'c': {'d': {'e': 4, 'f': 5}}}\n >>> d.intersect(\"tests/test.yaml\").dict()\n {'a': 1}\n >>> d.intersect(n, recursive=False).dict()\n {}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.intersect(l).dict()\n {'a': 1}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._intersect(self, other, recursive)) # type: ignore\n@staticmethod\ndef _intersect(this: NestedDict, that: Iterable, recursive: bool = True) -> Mapping:\nret: NestedDict = NestedDict()\nfor key, value in that:\nif key in this:\nif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:\nintersects = this[key].intersect(value)\nif intersects:\nret[key] = intersects\nelif this[key] == value:\nret[key] = value\nreturn ret\ndef difference( # pylint: disable=W0221, C0103\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Difference between `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.difference(n).dict()\n {'b': {'c': 3, 'd': 5}, 'd': 0}\n >>> d.difference(\"tests/test.yaml\").dict()\n {'b': 2, 'c': 3}\n >>> d.difference(n, recursive=False).dict()\n {'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._difference(self, other, recursive)) # type: ignore\n@staticmethod\ndef _difference(this: NestedDict, that: Iterable, recursive: bool = True) -> Mapping:\nret: NestedDict = NestedDict()\nfor key, value in that:\nif key not in this:\nret[key] = value\nelif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:\ndifferences = this[key].difference(value)\nif differences:\nret[key] = differences\nelif this[key] != value:\nret[key] = value\nreturn ret\n@contextmanager\ndef converting(self):\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ntry:\nself.setattr(\"convert_mapping\", True)\nyield\nfinally:\nself.setattr(\"convert_mapping\", convert_mapping)\ndef __contains__(self, name: Any) -> bool: # type: ignore\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif super().__contains__(name):\nself, name = self[name], rest # pylint: disable=W0642\nelse:\nreturn False\nreturn super().__contains__(name)\nexcept (TypeError, KeyError): # TypeError when name is not in self\nreturn False\nall_items()","text":"Get all items of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_items())\n[('a', 1), ('b.c', 2), ('b.d', 3)]\nchanfig/nested_dict.py Pythondef all_items(self) -> Generator:\nr\"\"\"\n Get all items of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_items())\n [('a', 1), ('b.c', 2), ('b.d', 3)]\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_items)\ndef all_items(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_items(value, key)\nelse:\nyield key, value\nreturn all_items(self)\nall_keys()","text":"Get all keys of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_keys())\n['a', 'b.c', 'b.d']\nchanfig/nested_dict.py Pythondef all_keys(self) -> Generator:\nr\"\"\"\n Get all keys of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_keys())\n ['a', 'b.c', 'b.d']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_keys)\ndef all_keys(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_keys(value, key)\nelse:\nyield key\nreturn all_keys(self)\nall_values()","text":"Get all values of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_values())\n[1, 2, 3]\nchanfig/nested_dict.py Pythondef all_values(self) -> Generator:\nr\"\"\"\n Get all values of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_values())\n [1, 2, 3]\n \"\"\"\nfor value in self.values():\nif isinstance(value, NestedDict):\nyield from value.all_values()\nelse:\nyield value\napply(func, *args, **kwargs)","text":"Recursively apply a function to NestedDict and its children.
This method is meant for non-in-place modification of obj, for example, to.
Parameters:
Name Type Description Defaultfunc Callable required See Also apply_: Apply an in-place operation. apply: Implementation of apply.
def func(d): \u2026 if isinstance(d, NestedDict): \u2026 d.t = 1 d = NestedDict() d.a = NestedDict() d.b = [NestedDict(),] d.c = (NestedDict(),) d.d = {NestedDict(),} d.apply(func).dict() {\u2018a\u2019: {}, \u2018b\u2019: [{}], \u2018c\u2019: ({},), \u2018d\u2019: ({},)}
Source code inchanfig/nested_dict.py Pythondef apply(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for non-in-place modification of `obj`, for example, [`to`][chanfig.NestedDict.to].\n Args:\n func (Callable):\n See Also:\n [`apply_`][chanfig.NestedDict.apply_]: Apply an in-place operation.\n [`apply`][chanfig.nested_dict.apply]: Implementation of `apply`.\n tionples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply(func).dict()\n {'a': {}, 'b': [{}], 'c': ({},), 'd': ({},)}\n \"\"\"\nreturn apply(self, func, *args, **kwargs)\napply_(func, *args, **kwargs)","text":"Recursively apply a function to NestedDict and its children.
This method is meant for in-place modification of obj, for example, freeze.
Parameters:
Name Type Description Defaultfunc Callable required See Also apply: Apply a non-in-place operation. apply_: Implementation of apply_ method.
Examples:
Python Console Session>>> def func(d):\n... if isinstance(d, NestedDict):\n... d.t = 1\n>>> d = NestedDict()\n>>> d.a = NestedDict()\n>>> d.b = [NestedDict(),]\n>>> d.c = (NestedDict(),)\n>>> d.d = {NestedDict(),}\n>>> d.apply_(func).dict()\n{'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\nchanfig/nested_dict.py Pythondef apply_(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for in-place modification of `obj`, for example, [`freeze`][chanfig.Config.freeze].\n Args:\n func (Callable):\n See Also:\n [`apply`][chanfig.NestedDict.apply]: Apply a non-in-place operation.\n [`apply_`][chanfig.nested_dict.apply_]: Implementation of `apply_` method.\n Examples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply_(func).dict()\n {'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\n \"\"\"\napply_(self, func, *args, **kwargs)\nreturn self\ndelete(name)","text":"Delete value from NestedDict.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n>>> d.i.d\n1013\n>>> d.f.n\n'chang'\n>>> d.delete('i.d')\n>>> d.dict()\n{'i': {}, 'f': {'n': 'chang'}}\n>>> d.i.d\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'd'\n>>> del d.f.n\n>>> d.dict()\n{'i': {}, 'f': {}}\n>>> d.f.n\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'n'\n>>> del d.e\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'e'\n>>> del d['f.n']\nTraceback (most recent call last):\nKeyError: 'n'\n>>> d.e = {'a': {'b': 1}}\n>>> del d['e.a.b']\nchanfig/nested_dict.py Pythondef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `NestedDict`.\n Args:\n name:\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> d.dict()\n {'i': {}, 'f': {'n': 'chang'}}\n >>> d.i.d\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'd'\n >>> del d.f.n\n >>> d.dict()\n {'i': {}, 'f': {}}\n >>> d.f.n\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'n'\n >>> del d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> del d['f.n']\n Traceback (most recent call last):\n KeyError: 'n'\n >>> d.e = {'a': {'b': 1}}\n >>> del d['e.a.b']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\n# if value is a python dict\nif not isinstance(self, NestedDict):\ndel self[name]\nreturn\nsuper().delete(name)\ndifference(other, recursive=True)","text":"Difference between NestedDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required recursive bool True Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n>>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n>>> d.difference(n).dict()\n{'b': {'c': 3, 'd': 5}, 'd': 0}\n>>> d.difference(\"tests/test.yaml\").dict()\n{'b': 2, 'c': 3}\n>>> d.difference(n, recursive=False).dict()\n{'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n>>> l = [('a', 1), ('d', 4)]\n>>> d.difference(l).dict()\n{'d': 4}\n>>> d.difference(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\nchanfig/nested_dict.py Pythondef difference( # pylint: disable=W0221, C0103\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Difference between `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.difference(n).dict()\n {'b': {'c': 3, 'd': 5}, 'd': 0}\n >>> d.difference(\"tests/test.yaml\").dict()\n {'b': 2, 'c': 3}\n >>> d.difference(n, recursive=False).dict()\n {'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._difference(self, other, recursive)) # type: ignore\nget(name, default=None, fallback=None)","text":"Get value from NestedDict.
Note that default has higher priority than default_factory.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If NestedDict does not contain name, return default. If default is not specified, return default_factory().
Raises:
Type DescriptionKeyError If NestedDict does not contain name and default/default_factory is not specified.
TypeError If name is not hashable.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n>>> d.get('i.d')\n1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.get('i.d', None)\n1013\n>>> d.get('f', 2)\n2\n>>> d.get('a.b', None)\n>>> d.f\nNestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n>>> del d.f\n>>> d = NestedDict({\"i.d\": 1013})\n>>> d.e\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'e'\n>>> d.e = {}\n>>> d.get('e.f', Null)\nTraceback (most recent call last):\nKeyError: 'f'\n>>> d.get('e.f')\n>>> d.get('e.f', 1)\n1\n>>> d.e.f\nTraceback (most recent call last):\nAttributeError: 'dict' object has no attribute 'f'\nchanfig/nested_dict.py Pythondef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `NestedDict`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `NestedDict` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('i.d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('a.b', None)\n >>> d.f\n NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n >>> del d.f\n >>> d = NestedDict({\"i.d\": 1013})\n >>> d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> d.e = {}\n >>> d.get('e.f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n >>> d.get('e.f')\n >>> d.get('e.f', 1)\n 1\n >>> d.e.f\n Traceback (most recent call last):\n AttributeError: 'dict' object has no attribute 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\nif fallback is None:\nfallback = self.getattr(\"fallback\", False)\nfallback_name = name.split(delimiter)[-1] if isinstance(name, str) else name\nfallback_values = []\ntry:\nwhile isinstance(name, str) and delimiter in name:\nif fallback and fallback_name in self:\nfallback_values.append(self.get(fallback_name))\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (KeyError, AttributeError, TypeError):\nif fallback and fallback_values:\nreturn fallback_values[-1]\nif default is not Null:\nreturn default\nraise KeyError(name) from None\nif (fallback and fallback_values) and (not isinstance(self, Iterable) or name not in self):\nreturn fallback_values[-1]\n# if value is a python dict\nif not isinstance(self, NestedDict):\nif name not in self and default is not Null:\nreturn default\nreturn self[name]\nreturn super().get(name, default)\nintersect(other, recursive=True)","text":"Intersection of NestedDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required recursive bool True Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n>>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n>>> d.intersect(n).dict()\n{'c': {'d': {'e': 4, 'f': 5}}}\n>>> d.intersect(\"tests/test.yaml\").dict()\n{'a': 1}\n>>> d.intersect(n, recursive=False).dict()\n{}\n>>> l = [('a', 1), ('d', 4)]\n>>> d.intersect(l).dict()\n{'a': 1}\n>>> d.intersect(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\nchanfig/nested_dict.py Pythondef intersect( # pylint: disable=W0221\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Intersection of `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.intersect(n).dict()\n {'c': {'d': {'e': 4, 'f': 5}}}\n >>> d.intersect(\"tests/test.yaml\").dict()\n {'a': 1}\n >>> d.intersect(n, recursive=False).dict()\n {}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.intersect(l).dict()\n {'a': 1}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._intersect(self, other, recursive)) # type: ignore\npop(name, default=Null)","text":"Pop value from NestedDict.
Parameters:
Name Type Description Defaultname Any required default Any Null Returns:
Name Type Descriptionvalue Any If NestedDict does not contain name, return default.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n>>> d.pop('i.d')\n1013\n>>> d.pop('i.d', True)\nTrue\n>>> d.pop('i.d')\nTraceback (most recent call last):\nKeyError: 'd'\n>>> d.pop('e')\nTraceback (most recent call last):\nKeyError: 'e'\n>>> d.pop('e.f')\nTraceback (most recent call last):\nKeyError: 'f'\nchanfig/nested_dict.py Pythondef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `NestedDict`.\n Args:\n name:\n default:\n Returns:\n value: If `NestedDict` does not contain `name`, return `default`.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n >>> d.pop('i.d')\n 1013\n >>> d.pop('i.d', True)\n True\n >>> d.pop('i.d')\n Traceback (most recent call last):\n KeyError: 'd'\n >>> d.pop('e')\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.pop('e.f')\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif not isinstance(self, dict) or name not in self:\nif default is not Null:\nreturn default\nraise KeyError(name)\nreturn super().pop(name)\nset(name, value, convert_mapping=None)","text":"Set value of NestedDict.
Parameters:
Name Type Description Defaultname Any required value Any required convert_mapping bool | None Whether to convert Mapping to NestedDict. Defaults to self.convert_mapping.
None Examples:
Python Console Session>>> d = NestedDict(default_factory=NestedDict)\n>>> d.set('i.d', 1013)\n>>> d.get('i.d')\n1013\n>>> d.dict()\n{'i': {'d': 1013}}\n>>> d['f.n'] = 'chang'\n>>> d.f.n\n'chang'\n>>> d.n.l = 'liu'\n>>> d['n.l']\n'liu'\n>>> d['f.n.e'] = \"error\"\nTraceback (most recent call last):\nValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n>>> d['f.n.e.a'] = \"error\"\nTraceback (most recent call last):\nKeyError: 'e'\n>>> d.f.n.e.a = \"error\"\nTraceback (most recent call last):\nAttributeError: 'str' object has no attribute 'e'\n>>> d.setattr('convert_mapping', True)\n>>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n>>> d.a.b.c.d\n1\n>>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n>>> d.c.d['e.f']\n2\n>>> d.setattr('convert_mapping', False)\n>>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n>>> d['e.f']['c.d']\n1\nchanfig/nested_dict.py Pythondef set( # pylint: disable=W0221\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `NestedDict`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Examples:\n >>> d = NestedDict(default_factory=NestedDict)\n >>> d.set('i.d', 1013)\n >>> d.get('i.d')\n 1013\n >>> d.dict()\n {'i': {'d': 1013}}\n >>> d['f.n'] = 'chang'\n >>> d.f.n\n 'chang'\n >>> d.n.l = 'liu'\n >>> d['n.l']\n 'liu'\n >>> d['f.n.e'] = \"error\"\n Traceback (most recent call last):\n ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n >>> d['f.n.e.a'] = \"error\"\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.f.n.e.a = \"error\"\n Traceback (most recent call last):\n AttributeError: 'str' object has no attribute 'e'\n >>> d.setattr('convert_mapping', True)\n >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.a.b.c.d\n 1\n >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.c.d['e.f']\n 2\n >>> d.setattr('convert_mapping', False)\n >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n >>> d['e.f']['c.d']\n 1\n \"\"\"\n# pylint: disable=W0642\nfull_name = name\ndelimiter = self.getattr(\"delimiter\", \".\")\nif convert_mapping is None:\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ndefault_factory = self.getattr(\"default_factory\", self.empty)\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif name in dir(self) and isinstance(getattr(self.__class__, name), (property, cached_property)):\nself, name = getattr(self, name), rest\nelif name not in self and isinstance(self, Mapping):\ndefault = (\nself.__missing__(name, default_factory()) if hasattr(self, \"__missing__\") else default_factory()\n)\nself, name = default, rest\nelse:\nself, name = self[name], rest\nif isinstance(self, NestedDict):\ndefault_factory = self.getattr(\"default_factory\", self.empty)\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif (\nconvert_mapping\nand isinstance(value, Mapping)\nand not isinstance(value, default_factory if isinstance(default_factory, type) else type(self))\nand not isinstance(value, Variable)\n):\ntry:\nvalue = default_factory(**value)\nexcept TypeError:\nvalue = default_factory(value)\nif isinstance(self, NestedDict):\nsuper().set(name, value)\nelif isinstance(self, Mapping):\ndict.__setitem__(self, name, value)\nelse:\nraise ValueError(\nf\"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`.\"\n)\nsort(key=None, reverse=False, recursive=True)","text":"Sort NestedDict.
Parameters:
Name Type Description Defaultrecursive bool Whether to apply sort recursively.
True Returns:
Type DescriptionNestedDict Examples:
Python Console Session>>> l = [1]\n>>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n>>> d.sort().dict()\n{'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n>>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n>>> d.sort().dict()\n{'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n>>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n>>> d.sort(recursive=False).dict()\n{'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n>>> l.append(2)\n>>> d.b.e.f\n[1, 2]\nchanfig/nested_dict.py Pythondef sort(self, key: Callable | None = None, reverse: bool = False, recursive: bool = True) -> NestedDict:\nr\"\"\"\n Sort `NestedDict`.\n Args:\n recursive (bool): Whether to apply `sort` recursively.\n Returns:\n (NestedDict):\n Examples:\n >>> l = [1]\n >>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort(recursive=False).dict()\n {'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n >>> l.append(2)\n >>> d.b.e.f\n [1, 2]\n \"\"\"\nif recursive:\nfor value in self.values():\nif isinstance(value, FlatDict):\nvalue.sort(key=key, reverse=reverse)\nreturn super().sort(key=key, reverse=reverse) # type: ignore\nvalidate()","text":"Validate NestedDict.
Raises:
Type DescriptionTypeError If Variable has invalid type.
ValueError If Variable has invalid value.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n>>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\nTraceback (most recent call last):\nTypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n>>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\nTraceback (most recent call last):\nValueError: 'd' has invalid value. Value -1 is not valid.\nchanfig/nested_dict.py Pythondef validate(self) -> None:\nr\"\"\"\n Validate `NestedDict`.\n Raises:\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n >>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n ValueError: 'd' has invalid value. Value -1 is not valid.\n \"\"\"\nself.apply_(self._validate)\n Bases: ArgumentParser
Parser to parse command-line arguments for CHANfiG.
ConfigParser is a subclass of argparse.ArgumentParser. It provides a new parse method to parse command-line arguments to CHANfiG.Config object.
Different to ArgumentParser.parse_args, ConfigParser.parse will try to parse any command-line arguments, even if they are not pre-defined by ArgumentParser.add_argument. This allows to relief the burden of adding tons of arguments for each tuneable parameter. In the meantime, there is no mechanism to notify you if you made a typo in command-line arguments.
Note that ArgumentParser.parse_args method is not overridden in ConfigParser. This is because it is still possible to construct CHANfiG.Config with ArgumentParser.parse_args, which has strict checking on command-line arguments.
chanfig/parser.py Pythonclass ConfigParser(ArgumentParser): # pylint: disable=C0115\nr\"\"\"\n Parser to parse command-line arguments for CHANfiG.\n `ConfigParser` is a subclass of `argparse.ArgumentParser`.\n It provides a new `parse` method to parse command-line arguments to `CHANfiG.Config` object.\n Different to `ArgumentParser.parse_args`, `ConfigParser.parse` will try to parse any command-line arguments,\n even if they are not pre-defined by `ArgumentParser.add_argument`.\n This allows to relief the burden of adding tons of arguments for each tuneable parameter.\n In the meantime, there is no mechanism to notify you if you made a typo in command-line arguments.\n Note that `ArgumentParser.parse_args` method is not overridden in `ConfigParser`.\n This is because it is still possible to construct `CHANfiG.Config` with `ArgumentParser.parse_args`,\n which has strict checking on command-line arguments.\n \"\"\"\ndef __init__(self, *args: Any, **kwargs: Any):\nsuper().__init__(*args, **kwargs)\nself._registries[\"action\"][None] = StoreAction\nself._registries[\"action\"][\"store\"] = StoreAction\ndef parse_args( # type: ignore\nself, args: Sequence[str] | None = None, namespace: Namespace | None = None\n) -> NestedDict:\nparsed = super().parse_args(args, namespace)\nif isinstance(parsed, Namespace):\nparsed = vars(parsed) # type: ignore\nif not isinstance(parsed, NestedDict):\nparsed = NestedDict({key: value for key, value in parsed.items() if value is not Null}) # type: ignore\nfor key, value in parsed.all_items():\nwith suppress(TypeError, ValueError, SyntaxError):\nvalue = literal_eval(value)\nparsed[key] = value\nreturn parsed # type: ignore\ndef parse( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | NestedDict | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse_config`][chanfig.ConfigParser.parse_config]: Only parse valid config arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n {'i': {'d': 1013}, 'f': {'n': 'chang'}}\n Values in command line overrides values in `default_config` file.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n {'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n Values in `default_config` file overrides values in `Config` object.\n >>> p = ConfigParser()\n >>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n {'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n ValueError will be raised when `default_config` is specified but not presented in command line.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config').dict()\n Traceback (most recent call last):\n RuntimeError: default_config is set to config, but not found in args.\n ValueError will be suppressed when `default_config` is specified bug not presented in command line,\n and `no_default_config_action` is set to `ignore` or `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n {'a': 2}\n ValueError will be raised when `no_default_config_action` is not in `raise`, `ignore`, and `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\n Traceback (most recent call last):\n ValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nfrom .config import Config # pylint: disable=C0415\nconfig = Config()\nelse:\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\n# add the command-line arguments\nkey_value_args = []\nfor arg in args:\nif args == \"--\":\nbreak\nif arg.startswith(\"--\"):\nkey_value_args.append(arg.split(\"=\", maxsplit=1))\nelse:\nif not key_value_args:\ncontinue\nkey_value_args[-1].append(arg)\nfor key_value in key_value_args:\nif key_value[0] not in self:\nif len(key_value) > 2:\nself.add_argument(key_value[0], nargs=\"+\")\nelse:\nself.add_argument(key_value[0])\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\ndef parse_config( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse`][chanfig.ConfigParser.parse]: Parse all command-line arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n {'a': 1}\n You can only parse argument that is defined in `Config`.\n error: unrecognized arguments: --b 1\n >>> p = ConfigParser()\n >>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict() # doctest: +SKIP\n Traceback (most recent call last):\n SystemExit: 2\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nraise ValueError(\"config must be specified\")\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\ndef add_config_arguments(self, config):\nfor key, value in config.all_items():\nif isinstance(value, Variable):\ndtype = value._type or value.dtype # pylint: disable=W0212\nelif value is not None:\ndtype = type(value)\nelse:\ndtype = None\nname = \"--\" + key\nif name not in self:\nhelp = value._help if isinstance(value, Variable) else None # pylint: disable=W0212,W0622\nif isinstance(value, (list, tuple, dict, set)):\nself.add_argument(name, type=dtype, nargs=\"+\", help=help, dest=key)\nelse:\nself.add_argument(name, type=dtype, help=help, dest=key)\ndef merge_default_config(self, parsed, default_config: str, no_default_config_action: str = \"raise\") -> NestedDict:\nmessage = f\"default_config is set to {default_config}, but not found in args.\"\nif default_config in parsed:\npath = parsed[default_config]\nwarn(f\"Config has 'default_config={path}' specified, its values will override values in Config\")\nreturn NestedDict.load(path).merge(parsed) # type: ignore\nif no_default_config_action == \"ignore\":\npass\nelif no_default_config_action == \"warn\":\nwarn(message, category=RuntimeWarning, stacklevel=2)\nelse:\nraise RuntimeError(message)\nreturn parsed\n@staticmethod\ndef identity(string):\nr\"\"\"\n https://stackoverflow.com/questions/69896931/cant-pickle-local-object-argumentparser-init-locals-identity\n \"\"\"\nreturn string\ndef __contains__(self, name: str):\nif name in self._option_string_actions:\nreturn True\nreturn False\nidentity(string) staticmethod","text":"Source code in chanfig/parser.py Python@staticmethod\ndef identity(string):\nr\"\"\"\n https://stackoverflow.com/questions/69896931/cant-pickle-local-object-argumentparser-init-locals-identity\n \"\"\"\nreturn string\nparse(args=None, config=None, default_config=None, no_default_config_action='raise')","text":"Parse the arguments for Config.
You may optionally specify a name for default_config, and CHANfiG will read the file under this name.
There are three levels of config:
Config parsed into this method,default_config (if specified),Higher levels override lower levels (i.e. 3 > 2 > 1).
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to Config.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' Returns:
Name Type Descriptionconfig Config The parsed Config.
Raises:
Type DescriptionValueError If default_config is specified but not found in args, and no_default_config_action is neither warn nor ignore.
ValueError If no_default_config_action is not in raise, warn and ignore.
parse_config: Only parse valid config arguments.
Examples:
Note that all examples uses NestedDict instead of Config for avoiding circular import.
Python Console Session>>> p = ConfigParser()\n>>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n{'i': {'d': 1013}, 'f': {'n': 'chang'}}\nValues in command line overrides values in default_config file.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n{'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\nValues in default_config file overrides values in Config object.
>>> p = ConfigParser()\n>>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n{'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\nValueError will be raised when default_config is specified but not presented in command line.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config').dict()\nTraceback (most recent call last):\nRuntimeError: default_config is set to config, but not found in args.\nValueError will be suppressed when default_config is specified bug not presented in command line, and no_default_config_action is set to ignore or warn.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n{'a': 2}\nValueError will be raised when no_default_config_action is not in raise, ignore, and warn.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\nTraceback (most recent call last):\nValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\nchanfig/parser.py Pythondef parse( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | NestedDict | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse_config`][chanfig.ConfigParser.parse_config]: Only parse valid config arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n {'i': {'d': 1013}, 'f': {'n': 'chang'}}\n Values in command line overrides values in `default_config` file.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n {'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n Values in `default_config` file overrides values in `Config` object.\n >>> p = ConfigParser()\n >>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n {'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n ValueError will be raised when `default_config` is specified but not presented in command line.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config').dict()\n Traceback (most recent call last):\n RuntimeError: default_config is set to config, but not found in args.\n ValueError will be suppressed when `default_config` is specified bug not presented in command line,\n and `no_default_config_action` is set to `ignore` or `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n {'a': 2}\n ValueError will be raised when `no_default_config_action` is not in `raise`, `ignore`, and `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\n Traceback (most recent call last):\n ValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nfrom .config import Config # pylint: disable=C0415\nconfig = Config()\nelse:\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\n# add the command-line arguments\nkey_value_args = []\nfor arg in args:\nif args == \"--\":\nbreak\nif arg.startswith(\"--\"):\nkey_value_args.append(arg.split(\"=\", maxsplit=1))\nelse:\nif not key_value_args:\ncontinue\nkey_value_args[-1].append(arg)\nfor key_value in key_value_args:\nif key_value[0] not in self:\nif len(key_value) > 2:\nself.add_argument(key_value[0], nargs=\"+\")\nelse:\nself.add_argument(key_value[0])\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\nparse_config(args=None, config=None, default_config=None, no_default_config_action='raise')","text":"Parse the arguments for Config.
You may optionally specify a name for default_config, and CHANfiG will read the file under this name.
There are three levels of config:
Config parsed into this method,default_config (if specified),Higher levels override lower levels (i.e. 3 > 2 > 1).
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to Config.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' Returns:
Name Type Descriptionconfig Config The parsed Config.
Raises:
Type DescriptionValueError If default_config is specified but not found in args, and no_default_config_action is neither warn nor ignore.
ValueError If no_default_config_action is not in raise, warn and ignore.
parse: Parse all command-line arguments.
Examples:
Note that all examples uses NestedDict instead of Config for avoiding circular import.
Python Console Session>>> p = ConfigParser()\n>>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n{'a': 1}\nYou can only parse argument that is defined in Config. error: unrecognized arguments: \u2013b 1
>>> p = ConfigParser()\n>>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict()\nTraceback (most recent call last):\nSystemExit: 2\nchanfig/parser.py Pythondef parse_config( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse`][chanfig.ConfigParser.parse]: Parse all command-line arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n {'a': 1}\n You can only parse argument that is defined in `Config`.\n error: unrecognized arguments: --b 1\n >>> p = ConfigParser()\n >>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict() # doctest: +SKIP\n Traceback (most recent call last):\n SystemExit: 2\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nraise ValueError(\"config must be specified\")\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\n Bases: NestedDict
Registry for components.
Registry provides 3 core functionalities:
To facilitate the usage scenario, registry is designed to be a decorator. You could register a component by simply calling registry.register, and it will be registered with its name. You may also specify the name of the component by calling registry.register(name=\"ComponentName\").
build makes it easy to construct a component from a configuration. build automatically determines the component to construct by the name field in the configuration. So you could either call registry.build(config) or registry.build(**config). Beyond this, build is just a syntax sugar for registry.init(registry.lookup(name), *args, **kwargs).
lookup is used to lookup for a component by its name. By default, lookup internally calls NestedDict.get, but you may override it to provide more functionalities.
init is used to construct a component. By default, init internally calls cls(*args, **kwargs), but you may override it to provide more functionalities.
Registry inherits from NestedDict.
Therefore, Registry comes in a nested structure by nature. You could create a sub-registry by simply calling registry.sub_registry = Registry, and access through registry.sub_registry.register().
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... @registry.register(\"Module1\")\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> module = registry.register(Module, \"Module2\")\n>>> registry\nRegistry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n)\n>>> module = registry.register(Module, \"Module\")\nTraceback (most recent call last):\nValueError: Component with name Module already registered.\n>>> registry.lookup(\"Module\")\n<class 'chanfig.registry.Module'>\n>>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n>>> # registry.register(Module)\n>>> module = registry.build(config[\"module\"])\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\nchanfig/registry.py Pythonclass Registry(NestedDict): # type: ignore\n\"\"\"\n `Registry` for components.\n Registry provides 3 core functionalities:\n - Register a new component.\n - Lookup for a component.\n - Build a component.\n To facilitate the usage scenario, `registry` is designed to be a decorator.\n You could register a component by simply calling `registry.register`, and it will be registered with its name.\n You may also specify the name of the component by calling `registry.register(name=\"ComponentName\")`.\n `build` makes it easy to construct a component from a configuration.\n `build` automatically determines the component to construct by the `name` field in the configuration.\n So you could either call `registry.build(config)` or `registry.build(**config)`.\n Beyond this, `build` is just a syntax sugar for `registry.init(registry.lookup(name), *args, **kwargs)`.\n `lookup` is used to lookup for a component by its name.\n By default, `lookup` internally calls `NestedDict.get`, but you may override it to provide more functionalities.\n `init` is used to construct a component.\n By default, `init` internally calls `cls(*args, **kwargs)`, but you may override it to provide more functionalities.\n Notes:\n `Registry` inherits from `NestedDict`.\n Therefore, `Registry` comes in a nested structure by nature.\n You could create a sub-registry by simply calling `registry.sub_registry = Registry`,\n and access through `registry.sub_registry.register()`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n >>> module = registry.register(Module, \"Module\")\n Traceback (most recent call last):\n ValueError: Component with name Module already registered.\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\noverride: bool = False\ndef __init__(self, override: bool | None = None, fallback: bool | None = None):\nsuper().__init__(fallback=fallback)\nif override is not None:\nself.setattr(\"override\", override)\ndef register(self, component: Any = None, name: Any | None = None) -> Callable:\nr\"\"\"\n Register a new component.\n Args:\n component: The component to register.\n name: The name of the component.\n Returns:\n component: The registered component.\n Registered component are expected to be `Callable`.\n Raises:\n ValueError: If the component with the same name already registered and `Registry.override=False`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n \"\"\"\nif name in self and not self.override:\nraise ValueError(f\"Component with name {name} already registered.\")\n# Registry.register()\nif name is not None:\nself.set(name, component)\nreturn component # type: ignore\n# @Registry.register\nif callable(component) and name is None:\nself.set(component.__name__, component)\nreturn component\n# @Registry.register()\ndef decorator(name: Any | None = None):\n@wraps(self.register)\ndef wrapper(component):\nif name is None:\nself.set(component.__name__, component)\nelse:\nself.set(name, component)\nreturn component\nreturn wrapper\nreturn decorator(component)\ndef lookup(self, name: str) -> Any:\nr\"\"\"\n Lookup for a component.\n Args:\n name:\n Returns:\n (Any): The component.\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n \"\"\"\nreturn self[name]\n@staticmethod\ndef init(cls: Callable, *args: Any, **kwargs: Any) -> Any: # type: ignore # pylint: disable=W0211\nr\"\"\"\n Constructor of component.\n Args:\n cls: The component to construct.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Examples:\n >>> class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> kwargs = {\"a\": 1, \"b\": 2}\n >>> module = Registry.init(Module, **kwargs)\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\nreturn cls(*args, **kwargs)\ndef build(self, name: str | Mapping, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Build a component.\n Args:\n name (str | Mapping):\n If its a `Mapping`, it must contain `\"name\"` as a member, the rest will be treated as `**kwargs`.\n Note that values in `kwargs` will override values in `name` if its a `Mapping`.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(**config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n >>> module = registry.build(config[\"module\"], a=2)\n >>> module.a\n 2\n \"\"\"\nif isinstance(name, Mapping):\nname = deepcopy(name)\nname, kwargs = name.pop(\"name\"), dict(name, **kwargs) # type: ignore\nreturn self.init(self.lookup(name), *args, **kwargs) # type: ignore\nbuild(name, *args, **kwargs)","text":"Build a component.
Parameters:
Name Type Description Defaultname str | Mapping If its a Mapping, it must contain \"name\" as a member, the rest will be treated as **kwargs. Note that values in kwargs will override values in name if its a Mapping.
*args Any The arguments to pass to the component.
() **kwargs Any The keyword arguments to pass to the component.
{} Returns:
Type DescriptionAny Raises:
Type DescriptionKeyError If the component is not registered.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n>>> # registry.register(Module)\n>>> module = registry.build(**config[\"module\"])\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\n>>> module = registry.build(config[\"module\"], a=2)\n>>> module.a\n2\nchanfig/registry.py Pythondef build(self, name: str | Mapping, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Build a component.\n Args:\n name (str | Mapping):\n If its a `Mapping`, it must contain `\"name\"` as a member, the rest will be treated as `**kwargs`.\n Note that values in `kwargs` will override values in `name` if its a `Mapping`.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(**config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n >>> module = registry.build(config[\"module\"], a=2)\n >>> module.a\n 2\n \"\"\"\nif isinstance(name, Mapping):\nname = deepcopy(name)\nname, kwargs = name.pop(\"name\"), dict(name, **kwargs) # type: ignore\nreturn self.init(self.lookup(name), *args, **kwargs) # type: ignore\ninit(*args, **kwargs) staticmethod","text":"Constructor of component.
Parameters:
Name Type Description Defaultcls Callable The component to construct.
required*args Any The arguments to pass to the component.
() **kwargs Any The keyword arguments to pass to the component.
{} Returns:
Type DescriptionAny Examples:
Python Console Session>>> class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> kwargs = {\"a\": 1, \"b\": 2}\n>>> module = Registry.init(Module, **kwargs)\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\nchanfig/registry.py Python@staticmethod\ndef init(cls: Callable, *args: Any, **kwargs: Any) -> Any: # type: ignore # pylint: disable=W0211\nr\"\"\"\n Constructor of component.\n Args:\n cls: The component to construct.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Examples:\n >>> class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> kwargs = {\"a\": 1, \"b\": 2}\n >>> module = Registry.init(Module, **kwargs)\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\nreturn cls(*args, **kwargs)\nlookup(name)","text":"Lookup for a component.
Parameters:
Name Type Description Defaultname str required Returns:
Type DescriptionAny The component.
Raises:
Type DescriptionKeyError If the component is not registered.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> registry.lookup(\"Module\")\n<class 'chanfig.registry.Module'>\nchanfig/registry.py Pythondef lookup(self, name: str) -> Any:\nr\"\"\"\n Lookup for a component.\n Args:\n name:\n Returns:\n (Any): The component.\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n \"\"\"\nreturn self[name]\nregister(component=None, name=None)","text":"Register a new component.
Parameters:
Name Type Description Defaultcomponent Any The component to register.
None name Any | None The name of the component.
None Returns:
Name Type Descriptioncomponent Callable The registered component. Registered component are expected to be Callable.
Raises:
Type DescriptionValueError If the component with the same name already registered and Registry.override=False.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... @registry.register(\"Module1\")\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> module = registry.register(Module, \"Module2\")\n>>> registry\nRegistry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n)\nchanfig/registry.py Pythondef register(self, component: Any = None, name: Any | None = None) -> Callable:\nr\"\"\"\n Register a new component.\n Args:\n component: The component to register.\n name: The name of the component.\n Returns:\n component: The registered component.\n Registered component are expected to be `Callable`.\n Raises:\n ValueError: If the component with the same name already registered and `Registry.override=False`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n \"\"\"\nif name in self and not self.override:\nraise ValueError(f\"Component with name {name} already registered.\")\n# Registry.register()\nif name is not None:\nself.set(name, component)\nreturn component # type: ignore\n# @Registry.register\nif callable(component) and name is None:\nself.set(component.__name__, component)\nreturn component\n# @Registry.register()\ndef decorator(name: Any | None = None):\n@wraps(self.register)\ndef wrapper(component):\nif name is None:\nself.set(component.__name__, component)\nelse:\nself.set(name, component)\nreturn component\nreturn wrapper\nreturn decorator(component)\n Bases: type
Metaclass for Singleton Classes.
Source code inchanfig/utils.py Pythonclass Singleton(type):\nr\"\"\"\n Metaclass for Singleton Classes.\n \"\"\"\n__instances__: Mapping[type, object] = {}\ndef __call__(cls, *args: Any, **kwargs: Any):\nif cls not in cls.__instances__:\ncls.__instances__[cls] = super().__call__(*args, **kwargs) # type: ignore\nreturn cls.__instances__[cls]\noptions: heading_level: 0
"},{"location":"utils/#chanfigutilsnull","title":"chanfig.utils.Null","text":"Null is an instance of NULL.
Since the metaclass of NULL is Singleton, it is advised to use obj is Null to determine if obj is Null.
NULL class.
get method in CHANfiG may accept None or Ellipse(...) as value of default. Therefore, it is mandatory to have a different default value for default.
Null is an instance of NULL and is recommended to be used as obj is Null.
chanfig/utils.py Pythonclass NULL(metaclass=Singleton):\nr\"\"\"\n NULL class.\n `get` method in CHANfiG may accept `None` or `Ellipse`(`...`) as value of `default`.\n Therefore, it is mandatory to have a different default value for `default`.\n `Null` is an instance of `NULL` and is recommended to be used as `obj is Null`.\n \"\"\"\ndef __repr__(self):\nreturn \"Null\"\ndef __nonzero__(self):\nreturn False\ndef __len__(self):\nreturn 0\ndef __call__(self, *args: Any, **kwargs: Any):\nreturn self\ndef __contains__(self, name):\nreturn False\ndef __iter__(self):\nreturn self\ndef __next__(self):\nraise StopIteration\ndef __getattr__(self, name):\nreturn self\ndef __getitem__(self, index):\nreturn self\noptions: heading_level: 0
Bases: JSONEncoder
JSON encoder for Config.
Source code inchanfig/utils.py Pythonclass JsonEncoder(JSONEncoder):\nr\"\"\"\n JSON encoder for Config.\n \"\"\"\ndef default(self, o: Any) -> Any:\nif hasattr(o, \"__json__\"):\nreturn o.__json__()\nreturn super().default(o)\noptions: heading_level: 0
Bases: SafeDumper
YAML Dumper for Config.
Source code inchanfig/utils.py Pythonclass YamlDumper(SafeDumper): # pylint: disable=R0903\nr\"\"\"\n YAML Dumper for Config.\n \"\"\"\ndef increase_indent(self, flow: bool = False, indentless: bool = False): # pylint: disable=W0235\nreturn super().increase_indent(flow, indentless)\noptions: heading_level: 0
Bases: SafeLoader
YAML Loader for Config.
Source code inchanfig/utils.py Pythonclass YamlLoader(SafeLoader): # pylint: disable=R0901,R0903\nr\"\"\"\n YAML Loader for Config.\n \"\"\"\noptions: heading_level: 0
"},{"location":"variable/","title":"Variable","text":" Bases: Generic[V]
Mutable wrapper for immutable objects.
Parameters:
Name Type Description Defaultvalue Any The value to wrap.
Null type type | None Desired type of the value.
None choices list | None Possible values of the value.
None validator Callable | None Callable that validates the value.
None required bool Whether the value is required.
False help str | None Help message of the value.
None Raises:
Type DescriptionRuntimeError If required is True and value is Null.
TypeError If type is specified and value is not an instance of type.
ValueError | If choices is specified and value is not in choices. If validator is specified and validator returns False.
Attributes:
Name Type Descriptionvalue Any The wrapped value.
dtype type The type of the wrapped value.
NotesVariable by default wrap the instance type to type of the wrapped object. Therefore, isinstance(Variable(1), int) will return True.
To temporarily disable this behaviour, you can call context manager with Variable.unwrapped().
To permanently disable this behaviour, you can call Variable.unwrap().
Examples:
Python Console Session>>> v = Variable(1)\n>>> n = v\n>>> v, n\n(1, 1)\n>>> v += 1\n>>> v, n\n(2, 2)\n>>> v.value = 3\n>>> v, n\n(3, 3)\n>>> n.set(4)\n>>> v, n\n(4, 4)\n>>> n = 5\n>>> v, n\n(4, 5)\n>>> f'{v} < {n}'\n'4 < 5'\n>>> isinstance(v, int)\nTrue\n>>> type(v)\n<class 'chanfig.variable.Variable'>\n>>> v.dtype\n<class 'int'>\n>>> with v.unwrapped():\n... isinstance(v, int)\nFalse\n>>> v = Variable('hello')\n>>> f'{v}, world!'\n'hello, world!'\n>>> v += ', world!'\n>>> v\n'hello, world!'\n>>> \"hello\" in v\nTrue\nchanfig/variable.py Pythonclass Variable(Generic[V]): # pylint: disable=R0902\nr\"\"\"\n Mutable wrapper for immutable objects.\n Args:\n value: The value to wrap.\n type: Desired type of the value.\n choices: Possible values of the value.\n validator: `Callable` that validates the value.\n required: Whether the value is required.\n help: Help message of the value.\n Raises:\n RuntimeError: If `required` is `True` and `value` is `Null`.\n TypeError: If `type` is specified and `value` is not an instance of `type`.\n ValueError: |\n If `choices` is specified and `value` is not in `choices`.\n If `validator` is specified and `validator` returns `False`.\n Attributes:\n value: The wrapped value.\n dtype: The type of the wrapped value.\n Notes:\n `Variable` by default wrap the instance type to type of the wrapped object.\n Therefore, `isinstance(Variable(1), int)` will return `True`.\n To temporarily disable this behaviour, you can call context manager `with Variable.unwrapped()`.\n To permanently disable this behaviour, you can call `Variable.unwrap()`.\n Examples:\n >>> v = Variable(1)\n >>> n = v\n >>> v, n\n (1, 1)\n >>> v += 1\n >>> v, n\n (2, 2)\n >>> v.value = 3\n >>> v, n\n (3, 3)\n >>> n.set(4)\n >>> v, n\n (4, 4)\n >>> n = 5\n >>> v, n\n (4, 5)\n >>> f'{v} < {n}'\n '4 < 5'\n >>> isinstance(v, int)\n True\n >>> type(v)\n <class 'chanfig.variable.Variable'>\n >>> v.dtype\n <class 'int'>\n >>> with v.unwrapped():\n ... isinstance(v, int)\n False\n >>> v = Variable('hello')\n >>> f'{v}, world!'\n 'hello, world!'\n >>> v += ', world!'\n >>> v\n 'hello, world!'\n >>> \"hello\" in v\n True\n \"\"\"\nwrap_type: bool = True\n_storage: List[Any]\n_type: Optional[type] = None\n_choices: Optional[list] = None\n_validator: Optional[Callable] = None\n_required: bool = False\n_help: Optional[str] = None\ndef __init__( # pylint: disable=R0913\nself,\nvalue: Any = Null,\ntype: type | None = None, # pylint: disable=W0622\nchoices: list | None = None,\nvalidator: Callable | None = None,\nrequired: bool = False,\nhelp: str | None = None, # pylint: disable=W0622\n) -> None:\nself._storage = [value]\nself._type = type\nself._choices = choices\nself._validator = validator\nself._required = required\nself._help = help\n@property # type: ignore\ndef __class__(self) -> type:\nreturn self.value.__class__ if self.wrap_type else type(self)\n@property\ndef value(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self._storage[0]\n@value.setter\ndef value(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n \"\"\"\nself.validate(value)\nself._storage[0] = self._get_value(value)\n@property\ndef dtype(self) -> type:\nr\"\"\"\n Data type of the object wrapped in `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> type(id)\n <class 'chanfig.variable.Variable'>\n >>> id.dtype\n <class 'int'>\n >>> issubclass(id.dtype, int)\n True\n \"\"\"\nreturn self.value.__class__\n@property\ndef storage(self) -> list[Any]:\nr\"\"\"\n Storage of `Variable`.\n \"\"\"\nreturn self._storage\n@property\ndef type(self) -> type | None:\nreturn self._type\n@property\ndef choices(self) -> list | None:\nreturn self._choices\n@property\ndef validator(self) -> Callable | None:\nreturn self._validator\n@property\ndef required(self) -> bool:\nreturn self._required\n@property\ndef help(self) -> str:\nreturn self._help or \"\"\ndef validate(self, *args) -> None:\nr\"\"\"\n Validate if the value is valid.\n \"\"\"\nif len(args) == 0:\nvalue = self.value\nelif len(args) == 1:\nvalue = args[0]\nelse:\nraise ValueError(\"Too many arguments.\")\nif self._required and value is Null:\nraise RuntimeError(\"Value is required.\")\nif self._type is not None and not isinstance(value, self._type):\nraise TypeError(f\"Value {value} is not of type {self._type}.\")\nif self._choices is not None and value not in self._choices:\nraise ValueError(f\"Value {value} is not in choices {self._choices}.\")\nif self._validator is not None and not self._validator(value):\nraise ValueError(f\"Value {value} is not valid.\")\ndef get(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self.value\ndef set(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n `Variable.set` is extremely useful when you want to change the value without changing the reference.\n In `FlatDict.set`, all assignments of `Variable` calls `Variable.set` Internally.\n \"\"\"\nself.value = value\ndef __get__(self, obj, objtype=None):\nreturn self\ndef __set__(self, obj, value):\nself.value = value\ndef to(self, cls: Callable) -> Any: # pylint: disable=C0103\nr\"\"\"\n Convert the object wrapped in `Variable` to target `cls`.\n Args:\n cls: The type to convert to.\n Examples:\n >>> id = Variable(1013)\n >>> id.to(float)\n 1013.0\n >>> id.to(str)\n '1013.0'\n \"\"\"\nself.value = cls(self.value)\nreturn self\ndef int(self) -> int:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `int`.\n Examples:\n >>> id = Variable(1013.0)\n >>> id.int()\n 1013\n \"\"\"\nreturn self.to(int)\ndef float(self) -> float:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.float()\n 1013.0\n \"\"\"\nreturn self.to(float)\ndef str(self) -> str:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.str()\n '1013'\n \"\"\"\nreturn self.to(str)\ndef wrap(self) -> None:\nr\"\"\"\n Wrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n >>> id.wrap()\n >>> isinstance(id, int)\n True\n \"\"\"\nself.wrap_type = True\ndef unwrap(self) -> None:\nr\"\"\"\n Unwrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n \"\"\"\nself.wrap_type = False\n@contextmanager\ndef unwrapped(self):\nr\"\"\"\n Context manager which temporarily unwrap the `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> isinstance(id, int)\n True\n >>> with id.unwrapped():\n ... isinstance(id, int)\n False\n \"\"\"\nwrap_type = self.wrap_type\nself.wrap_type = False\ntry:\nyield self\nfinally:\nself.wrap_type = wrap_type\n@staticmethod\ndef _get_value(obj) -> Any:\nif isinstance(obj, Variable):\nreturn obj.value\nreturn obj\ndef __getattr__(self, attr) -> Any:\nreturn getattr(self.value, attr)\ndef __lt__(self, other) -> bool:\nreturn self.value < self._get_value(other)\ndef __le__(self, other) -> bool:\nreturn self.value <= self._get_value(other)\ndef __eq__(self, other) -> bool:\nreturn self.value == self._get_value(other)\ndef __ne__(self, other) -> bool:\nreturn self.value != self._get_value(other)\ndef __ge__(self, other) -> bool:\nreturn self.value >= self._get_value(other)\ndef __gt__(self, other) -> bool:\nreturn self.value > self._get_value(other)\ndef __index__(self):\nreturn self.value.__index__()\ndef __invert__(self):\nreturn ~self.value\ndef __abs__(self):\nreturn abs(self.value)\ndef __add__(self, other):\nreturn Variable(self.value + self._get_value(other))\ndef __radd__(self, other):\nreturn Variable(self._get_value(other) + self.value)\ndef __iadd__(self, other):\nself.value += self._get_value(other)\nreturn self\ndef __and__(self, other):\nreturn Variable(self.value & self._get_value(other))\ndef __rand__(self, other):\nreturn Variable(self._get_value(other) & self.value)\ndef __iand__(self, other):\nself.value &= self._get_value(other)\nreturn self\ndef __floordiv__(self, other):\nreturn Variable(self.value // self._get_value(other))\ndef __rfloordiv__(self, other):\nreturn Variable(self._get_value(other) // self.value)\ndef __ifloordiv__(self, other):\nself.value //= self._get_value(other)\nreturn self\ndef __mod__(self, other):\nreturn Variable(self.value % self._get_value(other))\ndef __rmod__(self, other):\nreturn Variable(self._get_value(other) % self.value)\ndef __imod__(self, other):\nself.value %= self._get_value(other)\nreturn self\ndef __mul__(self, other):\nreturn Variable(self.value * self._get_value(other))\ndef __rmul__(self, other):\nreturn Variable(self._get_value(other) * self.value)\ndef __imul__(self, other):\nself.value *= self._get_value(other)\nreturn self\ndef __matmul__(self, other):\nreturn Variable(self.value @ self._get_value(other))\ndef __rmatmul__(self, other):\nreturn Variable(self._get_value(other) @ self.value)\ndef __imatmul__(self, other):\nself.value @= self._get_value(other)\nreturn self\ndef __pow__(self, other):\nreturn Variable(self.value ** self._get_value(other))\ndef __rpow__(self, other):\nreturn Variable(self._get_value(other) ** self.value)\ndef __ipow__(self, other):\nself.value **= self._get_value(other)\nreturn self\ndef __truediv__(self, other):\nreturn Variable(self.value / self._get_value(other))\ndef __rtruediv__(self, other):\nreturn Variable(self._get_value(other) / self.value)\ndef __itruediv__(self, other):\nself.value /= self._get_value(other)\nreturn self\ndef __sub__(self, other):\nreturn Variable(self.value - self._get_value(other))\ndef __rsub__(self, other):\nreturn Variable(self._get_value(other) - self.value)\ndef __isub__(self, other):\nself.value -= self._get_value(other)\nreturn self\ndef __copy__(self):\nreturn Variable(self.value)\ndef __deepcopy__(self, memo: Mapping | None = None):\nreturn Variable(copy(self.value))\ndef __format__(self, format_spec):\nreturn self.value if isinstance(self, str) else format(self.value, format_spec)\ndef __iter__(self):\nreturn iter(self.value)\ndef __next__(self):\nreturn next(self.value)\ndef __hash__(self):\nreturn hash(self.value)\ndef __repr__(self):\nreturn repr(self.value)\ndef __str__(self):\nreturn self.value if isinstance(self, str) else str(self.value)\ndef __json__(self):\nreturn self.value\ndef __contains__(self, name):\nreturn name in self.value\ndtype: type property","text":"Data type of the object wrapped in Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> type(id)\n<class 'chanfig.variable.Variable'>\n>>> id.dtype\n<class 'int'>\n>>> issubclass(id.dtype, int)\nTrue\nstorage: list[Any] property","text":"Storage of Variable.
value: Any property writable","text":"Fetch the object wrapped in Variable.
float()","text":"Convert the object wrapped in Variable to python float.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.float()\n1013.0\nchanfig/variable.py Pythondef float(self) -> float:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.float()\n 1013.0\n \"\"\"\nreturn self.to(float)\nget()","text":"Fetch the object wrapped in Variable.
chanfig/variable.py Pythondef get(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self.value\nint()","text":"Convert the object wrapped in Variable to python int.
Examples:
Python Console Session>>> id = Variable(1013.0)\n>>> id.int()\n1013\nchanfig/variable.py Pythondef int(self) -> int:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `int`.\n Examples:\n >>> id = Variable(1013.0)\n >>> id.int()\n 1013\n \"\"\"\nreturn self.to(int)\nset(value)","text":"Assign value to the object wrapped in Variable.
Variable.set is extremely useful when you want to change the value without changing the reference.
In FlatDict.set, all assignments of Variable calls Variable.set Internally.
chanfig/variable.py Pythondef set(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n `Variable.set` is extremely useful when you want to change the value without changing the reference.\n In `FlatDict.set`, all assignments of `Variable` calls `Variable.set` Internally.\n \"\"\"\nself.value = value\nstr()","text":"Convert the object wrapped in Variable to python float.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.str()\n'1013'\nchanfig/variable.py Pythondef str(self) -> str:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.str()\n '1013'\n \"\"\"\nreturn self.to(str)\nto(cls)","text":"Convert the object wrapped in Variable to target cls.
Parameters:
Name Type Description Defaultcls Callable The type to convert to.
requiredExamples:
Python Console Session>>> id = Variable(1013)\n>>> id.to(float)\n1013.0\n>>> id.to(str)\n'1013.0'\nchanfig/variable.py Pythondef to(self, cls: Callable) -> Any: # pylint: disable=C0103\nr\"\"\"\n Convert the object wrapped in `Variable` to target `cls`.\n Args:\n cls: The type to convert to.\n Examples:\n >>> id = Variable(1013)\n >>> id.to(float)\n 1013.0\n >>> id.to(str)\n '1013.0'\n \"\"\"\nself.value = cls(self.value)\nreturn self\nunwrap()","text":"Unwrap the type of Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.unwrap()\n>>> isinstance(id, int)\nFalse\nchanfig/variable.py Pythondef unwrap(self) -> None:\nr\"\"\"\n Unwrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n \"\"\"\nself.wrap_type = False\nunwrapped()","text":"Context manager which temporarily unwrap the Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> isinstance(id, int)\nTrue\n>>> with id.unwrapped():\n... isinstance(id, int)\nFalse\nchanfig/variable.py Python@contextmanager\ndef unwrapped(self):\nr\"\"\"\n Context manager which temporarily unwrap the `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> isinstance(id, int)\n True\n >>> with id.unwrapped():\n ... isinstance(id, int)\n False\n \"\"\"\nwrap_type = self.wrap_type\nself.wrap_type = False\ntry:\nyield self\nfinally:\nself.wrap_type = wrap_type\nvalidate(*args)","text":"Validate if the value is valid.
Source code inchanfig/variable.py Pythondef validate(self, *args) -> None:\nr\"\"\"\n Validate if the value is valid.\n \"\"\"\nif len(args) == 0:\nvalue = self.value\nelif len(args) == 1:\nvalue = args[0]\nelse:\nraise ValueError(\"Too many arguments.\")\nif self._required and value is Null:\nraise RuntimeError(\"Value is required.\")\nif self._type is not None and not isinstance(value, self._type):\nraise TypeError(f\"Value {value} is not of type {self._type}.\")\nif self._choices is not None and value not in self._choices:\nraise ValueError(f\"Value {value} is not in choices {self._choices}.\")\nif self._validator is not None and not self._validator(value):\nraise ValueError(f\"Value {value} is not valid.\")\nwrap()","text":"Wrap the type of Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.unwrap()\n>>> isinstance(id, int)\nFalse\n>>> id.wrap()\n>>> isinstance(id, int)\nTrue\nchanfig/variable.py Pythondef wrap(self) -> None:\nr\"\"\"\n Wrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n >>> id.wrap()\n >>> isinstance(id, int)\n True\n \"\"\"\nself.wrap_type = True\nCHANfiG \u200b\u5e0c\u671b\u200b\u80fd\u200b\u8ba9\u200b\u4f60\u200b\u7684\u200b\u914d\u7f6e\u200b\u66f4\u52a0\u200b\u7b80\u5355\u200b\u3002
\u200b\u8bad\u7ec3\u200b\u4e00\u4e2a\u200b\u673a\u5668\u200b\u5b66\u4e60\u200b\u6a21\u578b\u200b\u6709\u200b\u65e0\u6570\u4e2a\u200b\u53ef\u200b\u8c03\u8282\u200b\u7684\u200b\u53c2\u6570\u200b\u3002 \u200b\u4e3a\u4e86\u200b\u8c03\u8282\u200b\u6240\u6709\u200b\u53c2\u6570\u200b\uff0c\u200b\u7814\u7a76\u5458\u200b\u4eec\u200b\u5e38\u5e38\u200b\u9700\u8981\u200b\u64b0\u5199\u200b\u5de8\u5927\u200b\u7684\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u6709\u65f6\u200b\u751a\u81f3\u200b\u957f\u200b\u8fbe\u200b\u6570\u5343\u200b\u884c\u200b\u3002 \u200b\u5927\u591a\u6570\u200b\u53c2\u6570\u200b\u53ea\u662f\u200b\u65b9\u6cd5\u200b\u9ed8\u8ba4\u200b\u53c2\u6570\u200b\u7684\u200b\u7b80\u5355\u200b\u91cd\u590d\u200b\uff0c\u200b\u8fd9\u200b\u5bfc\u81f4\u200b\u4e86\u200b\u5f88\u591a\u200b\u4e0d\u5fc5\u8981\u200b\u7684\u200b\u58f0\u660e\u200b\u3002 \u200b\u6b64\u5916\u200b\uff0c\u200b\u8c03\u8282\u200b\u8fd9\u4e9b\u200b\u53c2\u6570\u200b\u540c\u6837\u200b\u5f88\u200b\u7e41\u7410\u200b\uff0c\u200b\u9700\u8981\u200b\u5b9a\u4f4d\u200b\u5e76\u200b\u6253\u5f00\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u4f5c\u51fa\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u4fdd\u5b58\u200b\u5173\u95ed\u200b\u3002 \u200b\u8fd9\u4e2a\u200b\u8fc7\u7a0b\u200b\u6d6a\u8d39\u200b\u4e86\u200b\u65e0\u6570\u200b\u7684\u200b\u5b9d\u8d35\u65f6\u95f4\u200b \u200b\u8fd9\u200b\u65e0\u7591\u200b\u662f\u200b\u4e00\u79cd\u200b\u72af\u7f6a\u200b \u3002 \u200b\u4f7f\u7528\u200bargparse\u200b\u53ef\u4ee5\u200b\u5728\u200b\u4e00\u5b9a\u200b\u7a0b\u5ea6\u200b\u4e0a\u200b\u7f13\u89e3\u200b\u8c03\u53c2\u200b\u7684\u200b\u4e0d\u53d8\u200b\uff0c\u200b\u4f46\u662f\u200b\uff0c\u200b\u8981\u200b\u8ba9\u200b\u4ed6\u200b\u548c\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u9002\u914d\u200b\u4f9d\u7136\u200b\u9700\u8981\u200b\u5f88\u591a\u200b\u5de5\u4f5c\u200b\uff0c\u200b\u5e76\u4e14\u200b\u7f3a\u4e4f\u200b\u5d4c\u5957\u200b\u4e5f\u200b\u9650\u5236\u200b\u4e86\u200b\u4ed6\u200b\u7684\u200b\u6f5c\u529b\u200b\u3002
CHANfiG \u200b\u65e8\u5728\u200b\u5e26\u6765\u200b\u6539\u53d8\u200b\u3002
\u200b\u4f60\u200b\u53ea\u200b\u9700\u8981\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u8f93\u5165\u200b\u4f60\u200b\u7684\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u628a\u200b\u5269\u4e0b\u200b\u7684\u200b\u4ea4\u7ed9\u200b CHANfiG\u3002
CHANfiG \u200b\u5f88\u5927\u200b\u7a0b\u5ea6\u200b\u4e0a\u200b\u542f\u53d1\u200b\u81ea\u200bYACS\u3002 \u200b\u4e0d\u540c\u4e8e\u200b YACS \u200b\u7684\u200b\u8303\u5f0f\u200b\uff08\u200b\u4ee3\u7801\u200b + \u200b\u5b9e\u9a8c\u200bE\u200b\u7684\u200bYACS\u200b\u914d\u7f6e\u6587\u4ef6\u200b (+ \u200b\u5916\u90e8\u200b\u4f9d\u8d56\u200b + \u200b\u786c\u4ef6\u200b + \u200b\u5176\u4ed6\u200b\u4ee4\u4eba\u8ba8\u538c\u200b\u7684\u200b\u672f\u8bed\u200b ...) = \u200b\u53ef\u200b\u91cd\u590d\u200b\u7684\u200b\u5b9e\u9a8c\u200bE\uff09\uff0c CHANfiG \u200b\u7684\u200b\u8303\u5f0f\u200b\u662f\u200b\uff1a
\u200b\u4ee3\u7801\u200b + \u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b (+ \u200b\u53ef\u9009\u200b\u7684\u200bCHANfiG\u200b\u914d\u7f6e\u6587\u4ef6\u200b + \u200b\u5916\u90e8\u200b\u4f9d\u8d56\u200b + \u200b\u786c\u4ef6\u200b + \u200b\u5176\u4ed6\u200b\u4ee4\u4eba\u8ba8\u538c\u200b\u7684\u200b\u672f\u8bed\u200b ...) = \u200b\u53ef\u200b\u91cd\u590d\u200b\u7684\u200b\u5b9e\u9a8c\u200bE (+ \u200b\u53ef\u9009\u200b\u7684\u200bCHANfiG\u200b\u914d\u7f6e\u6587\u4ef6\u200b)
\u200b\u4e00\u4e2a\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u53ef\u4ee5\u200b\u88ab\u200b\u770b\u4f5c\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7684\u200b\u5b57\u5178\u200b\u7ed3\u6784\u200b\u3002
\u200b\u4f46\u662f\u200b\uff0c\u200b\u9ed8\u8ba4\u200b\u7684\u200b Python \u200b\u5b57\u5178\u200b\u5341\u5206\u200b\u96be\u4ee5\u200b\u64cd\u4f5c\u200b\u3002
\u200b\u8bbf\u95ee\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u7684\u200b\u552f\u4e00\u200b\u65b9\u5f0f\u200b\u662f\u200bdict['name']\uff0c\u200b\u8fd9\u200b\u65e0\u7591\u200b\u662f\u200b\u6781\u5176\u200b\u7e41\u7410\u200b\u7684\u200b\u3002 \u200b\u66f4\u200b\u7cdf\u7cd5\u200b\u7684\u200b\uff0c\u200b\u5982\u679c\u200b\u8fd9\u4e2a\u200b\u5b57\u5178\u200b\u548c\u200b\u914d\u7f6e\u200b\u4e00\u6837\u200b\u662f\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\uff0c\u200b\u8bbf\u95ee\u200b\u6210\u5458\u200b\u5c06\u4f1a\u200b\u53d8\u6210\u200b\u7c7b\u4f3c\u200b\u4e8e\u200bdict['parent']['children']['name']\u200b\u7684\u200b\u6837\u5b50\u200b\u3002
\u200b\u591f\u200b\u4e86\u200b\u5c31\u662f\u200b\u591f\u200b\u4e86\u200b\uff0c\u200b\u662f\u200b\u65f6\u5019\u200b\u505a\u51fa\u200b\u6539\u53d8\u200b\u4e86\u200b\u3002
\u200b\u6211\u4eec\u200b\u9700\u8981\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u7684\u200b\u8bbf\u95ee\u200b\uff0c\u200b\u5e76\u4e14\u200b\u6211\u4eec\u200b\u73b0\u5728\u200b\u5c31\u200b\u9700\u8981\u200b\u3002 dict.name\u200b\u548c\u200bdict.parent.children.name\u200b\u662f\u200b\u6240\u6709\u200b\u4f60\u200b\u9700\u8981\u200b\u7684\u200b\u3002
\u200b\u5c3d\u7ba1\u200b\u6b64\u524d\u200b\u5df2\u7ecf\u200b\u6709\u200b\u5de5\u4f5c\u200b\u6765\u200b\u5b9e\u73b0\u200b\u7c7b\u4f3c\u200b\u7684\u200b\u5bf9\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u7684\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u3002\u200b\u4f46\u662f\u200b\u4ed6\u4eec\u200b\u7684\u200b Config \u200b\u5bf9\u8c61\u200b\u8981\u4e48\u200b\u4f7f\u7528\u200b\u4e00\u4e2a\u200b\u72ec\u7acb\u200b\u7684\u200b\u5b57\u5178\u200b\u6765\u200b\u5b58\u50a8\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u7684\u200b\u4fe1\u606f\u200b\uff08EasyDict\uff09\uff0c\u200b\u800c\u200b\u8fd9\u200b\u53ef\u80fd\u200b\u5bfc\u81f4\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u548c\u200b\u5b57\u5178\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u7684\u200b\u4e0d\u200b\u4e00\u81f4\u200b\uff1b\u200b\u8981\u4e48\u200b\u91cd\u65b0\u200b\u4f7f\u7528\u200b\u65e2\u6709\u200b\u7684\u200b__dict__\u200b\u7136\u540e\u200b\u5bf9\u200b\u5b57\u5178\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u8fdb\u884c\u200b\u91cd\u5b9a\u5411\u200b\uff08ml_collections\uff09\uff0c\u200b\u800c\u200b\u8fd9\u200b\u53ef\u80fd\u200b\u5bfc\u81f4\u200b\u5c5e\u6027\u200b\u548c\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u5b58\u5728\u200b\u51b2\u7a81\u200b\u3002
\u200b\u4e3a\u4e86\u200b\u89e3\u51b3\u200b\u4e0a\u8ff0\u200b\u9650\u5236\u200b\uff0c\u200b\u6211\u4eec\u200b\u7ee7\u627f\u200b\u4e86\u200b Python \u200b\u5185\u7f6e\u200b\u7684\u200bdict\u200b\u6765\u200b\u521b\u5efa\u200bFlatDict\u3001DefaultDict\u3001NestedDict\u3001Config\u200b\u548c\u200bRegistry\u3002 \u200b\u6211\u4eec\u200b\u540c\u65f6\u200b\u4ecb\u7ecd\u200b\u4e86\u200bVariable\u200b\u6765\u200b\u5728\u200b\u591a\u4e2a\u200b\u4f4d\u7f6e\u200b\u5171\u4eab\u200b\u503c\u200b\uff0c\u200b\u548c\u200bConfigParser\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b\u3002
FlatDict\u200b\u5728\u200b\u4e09\u4e2a\u200b\u65b9\u9762\u200b\u5bf9\u200b\u9ed8\u8ba4\u200b\u7684\u200bdict\u200b\u505a\u51fa\u200b\u6539\u8fdb\u200b\u3002
FlatDict\u200b\u652f\u6301\u200b\u53d8\u91cf\u200b\u63d2\u503c\u200b\u3002 \u200b\u5c06\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u8bbe\u7f6e\u200b\u4e3a\u200b${}\u200b\u5305\u88f9\u200b\u7684\u200b\u53e6\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u540d\u200b\uff0c\u200b\u7136\u540e\u200b\u8c03\u7528\u200binterpolate\u200b\u65b9\u6cd5\u200b\u3002 \u200b\u8fd9\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u5c06\u200b\u4f1a\u200b\u81ea\u52a8\u200b\u66ff\u6362\u200b\u4e3a\u200b\u53e6\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u3002
Python \u200b\u7684\u200bdict\u200b\u81ea\u200b Python 3.7 \u200b\u4e4b\u540e\u200b\u5c31\u662f\u200b\u6709\u5e8f\u200b\u7684\u200b\uff0c\u200b\u4f46\u662f\u200b\u5e76\u200b\u6ca1\u6709\u200b\u4e00\u4e2a\u200b\u5185\u7f6e\u200b\u7684\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u5bf9\u200b\u4e00\u4e2a\u200bdict\u200b\u8fdb\u884c\u200b\u6392\u5e8f\u200b\u3002FlatDict\u200b\u652f\u6301\u200bsort\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u7ba1\u7406\u200b\u4f60\u200b\u7684\u200b\u5b57\u5178\u200b\u3002
FlatDict\u200b\u5305\u62ec\u200b\u4e86\u200b\u4e00\u4e2a\u200bmerge\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u4ed6\u200b\u4f7f\u200b\u4f60\u200b\u80fd\u200b\u5c06\u200b\u4e00\u4e2a\u200bMapping\u3001Iterable\u200b\u6216\u8005\u200b\u4e00\u4e2a\u200b\u8def\u5f84\u200b\u5408\u5e76\u200b\u8fdb\u5165\u200b\u4e00\u4e2a\u200bFlatDict\u3002 \u200b\u4e0e\u200bupdate\u200b\u65b9\u6cd5\u200b\u4e0d\u540c\u200b\uff0cmerge\u200b\u65b9\u6cd5\u200b\u662f\u200b\u8d4b\u503c\u200b\u800c\u200b\u4e0d\u662f\u200b\u66ff\u6362\u200b\uff0c\u200b\u8fd9\u200b\u4f7f\u5f97\u200b\u4ed6\u200b\u80fd\u200b\u66f4\u597d\u200b\u7684\u200b\u4e0e\u200bDefaultDict\u200b\u914d\u5408\u200b\u4f7f\u7528\u200b\u3002
\u200b\u6b64\u5916\u200b\uff0cFlatDict\u200b\u5f15\u5165\u200b\u4e86\u200bdifference\u200b\u548c\u200bintersect\uff0c\u200b\u8fd9\u4e9b\u200b\u4f7f\u200b\u5176\u200b\u53ef\u4ee5\u200b\u975e\u5e38\u7b80\u5355\u200b\u7684\u200b\u5c06\u200bFlatDict\u200b\u548c\u200b\u5176\u4ed6\u200bMapping\u3001Iterable\u200b\u6216\u8005\u200b\u4e00\u4e2a\u200b\u8def\u5f84\u200b\u8fdb\u884c\u200b\u5bf9\u6bd4\u200b\u3002
FlatDict\u200b\u652f\u6301\u200b\u4e0e\u200b Pytorch Tensor \u200b\u7c7b\u4f3c\u200b\u7684\u200bto\u200b\u65b9\u6cd5\u200b\u3002 \u200b\u4f60\u200b\u53ef\u4ee5\u200b\u5f88\u200b\u7b80\u5355\u200b\u7684\u200b\u901a\u8fc7\u200b\u76f8\u540c\u200b\u7684\u200b\u65b9\u5f0f\u200b\u5c06\u200b\u6240\u6709\u200bFlatDict\u200b\u7684\u200b\u6210\u5458\u200b\u503c\u200b\u8f6c\u6362\u200b\u4e3a\u200b\u67d0\u79cd\u200b\u7c7b\u578b\u200b\u6216\u8005\u200b\u8f6c\u79fb\u200b\u5230\u200b\u67d0\u4e2a\u200b\u8bbe\u5907\u200b\u4e0a\u200b\u3002
FlatDict\u200b\u540c\u65f6\u200b\u96c6\u6210\u200b\u4e86\u200bcpu\u3001gpu (cuda)\u3001tpu (xla)\u200b\u65b9\u6cd5\u200b\u6765\u200b\u63d0\u4f9b\u200b\u66f4\u200b\u4fbf\u6377\u200b\u7684\u200b\u8bbf\u95ee\u200b\u3002
FlatDict\u200b\u652f\u6301\u200bjson\u3001jsons\u3001yaml\u200b\u548c\u200byamls\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5c06\u200bFlatDict\u200b\u5b58\u50a8\u200b\u5230\u200b\u6587\u4ef6\u200b\u6216\u8005\u200b\u8f6c\u6362\u6210\u200b\u5b57\u7b26\u4e32\u200b\u3002 \u200b\u5b83\u200b\u8fd8\u200b\u63d0\u4f9b\u200b\u4e86\u200bfrom_json\u3001from_jsons\u3001from_yaml\u200b\u548c\u200bfrom_yamls\u200b\u6765\u200b\u4ece\u200b\u4e00\u4e2a\u200b\u5b57\u7b26\u4e32\u200b\u6216\u8005\u200b\u6587\u4ef6\u200b\u4e2d\u200b\u6784\u5efa\u200bFlatDict\u3002
FlatDict\u200b\u4e5f\u200b\u5305\u62ec\u200b\u4e86\u200bdump\u200b\u548c\u200bload\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u4ed6\u4eec\u200b\u53ef\u4ee5\u200b\u4ece\u6587\u4ef6\u200b\u6269\u5c55\u540d\u200b\u4e2d\u200b\u81ea\u52a8\u200b\u63a8\u65ad\u200b\u7c7b\u578b\u200b\u7136\u540e\u200b\u5c06\u200bFlatDict\u200b\u5b58\u50a8\u200b\u5230\u200b\u6587\u4ef6\u200b\u4e2d\u200b/\u200b\u4ece\u6587\u4ef6\u200b\u4e2d\u200b\u52a0\u8f7d\u200bFlatDict\u3002
\u200b\u4e3a\u4e86\u200b\u6ee1\u8db3\u200b\u9ed8\u8ba4\u503c\u200b\u7684\u200b\u9700\u8981\u200b\uff0c\u200b\u6211\u4eec\u200b\u5305\u62ec\u200b\u4e86\u200b\u4e00\u4e2a\u200bDefaultDict\uff0c\u200b\u4ed6\u200b\u63a5\u53d7\u200bdefault_factory\u200b\u53c2\u6570\u200b\uff0c\u200b\u5e76\u200b\u548c\u200bcollections.defaultdict\u200b\u4e00\u6837\u200b\u5de5\u4f5c\u200b\u3002
\u200b\u7531\u4e8e\u200b\u5927\u591a\u6570\u200b\u914d\u7f6e\u200b\u90fd\u200b\u662f\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7684\u200b\u7ed3\u6784\u200b\uff0c\u200b\u6211\u4eec\u200b\u8fdb\u4e00\u6b65\u200b\u63d0\u51fa\u200b\u4e86\u200bNestedDict\u3002
\u200b\u57fa\u4e8e\u200bDefaultDict\uff0cNestedDict\u200b\u63d0\u4f9b\u200b\u4e86\u200ball_keys\u3001all_values\u3001all_items\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5141\u8bb8\u200b\u4e00\u6b21\u6027\u200b\u904d\u5386\u200b\u6574\u4e2a\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\u3002
NestedDict\u200b\u540c\u65f6\u200b\u63d0\u4f9b\u200b\u4e86\u200bapply\u200b\u548c\u200bapply_\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u5b83\u200b\u53ef\u4ee5\u200b\u4f7f\u200b\u64cd\u7eb5\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\u66f4\u52a0\u200b\u5bb9\u6613\u200b\u3002
Config\u200b\u901a\u8fc7\u200b\u4e24\u4e2a\u200b\u65b9\u9762\u200b\u6765\u200b\u8fdb\u4e00\u6b65\u200b\u63d0\u5347\u200b\u529f\u80fd\u6027\u200b\uff1a \u200b\u652f\u6301\u200bfreeze\u200b\u6765\u200b\u51bb\u7ed3\u200b\u548c\u200bdefrost\u200b\u89e3\u51bb\u200b\u5b57\u5178\u200b\u548c\u200b \u200b\u52a0\u5165\u200b\u5185\u7f6e\u200b\u7684\u200bConfigParser\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u8bed\u53e5\u200b\u3002
\u200b\u6ce8\u610f\u200bConfig\u200b\u9ed8\u8ba4\u8bbe\u7f6e\u200bdefault_factory=Config()\u200b\u6765\u200b\u63d0\u4f9b\u200b\u4fbf\u5229\u200b\u3002
Registry\u200b\u7ee7\u627f\u200b\u81ea\u200bNestedDict\uff0c\u200b\u5e76\u4e14\u200b\u63d0\u4f9b\u200bregister\u3001lookup\u200b\u548c\u200bbuild\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u6ce8\u518c\u200b\u6784\u9020\u51fd\u6570\u200b\u5e76\u200b\u4ece\u200bConfig\u200b\u6765\u200b\u521b\u5efa\u5bf9\u8c61\u200b\u3002
\u200b\u6709\u200b\u4e00\u4e2a\u200b\u503c\u200b\u5728\u200b\u591a\u4e2a\u200b\u5730\u65b9\u200b\u4ee5\u200b\u591a\u4e2a\u200b\u540d\u5b57\u200b\u51fa\u73b0\u200b\uff1f\u200b\u6211\u4eec\u200b\u7ed9\u200b\u4f60\u200b\u63d0\u4f9b\u200b\u63a9\u62a4\u200b\u3002
\u200b\u53ea\u8981\u200b\u5c06\u503c\u200b\u4ee5\u200bVariable\u200b\u5305\u88c5\u200b\uff0c\u200b\u7136\u540e\u200b\u6bcf\u5904\u200b\u66f4\u6539\u200b\u90fd\u200b\u4f1a\u200b\u5728\u200b\u5904\u5904\u200b\u4f53\u73b0\u200b\u3002
Variable\u200b\u540c\u65f6\u200b\u652f\u6301\u200btype\u3001choices\u3001validator\u3001required\u200b\u6765\u200b\u786e\u4fdd\u200b\u503c\u200b\u7684\u200b\u6b63\u786e\u6027\u200b\u3002
\u200b\u4e3a\u4e86\u200b\u66f4\u52a0\u200b\u7b80\u5355\u200b\uff0cVariable\u200b\u8fd8\u200b\u652f\u6301\u200bhelp\u200b\u6765\u200b\u5728\u200b\u4f7f\u7528\u200bConfigParser\u200b\u65f6\u200b\u63d0\u4f9b\u200b\u63cf\u8ff0\u200b\u3002
ConfigParser\u200b\u5728\u200bArgumentParser\u200b\u7684\u200b\u57fa\u7840\u200b\u4e4b\u4e0a\u200b\uff0c\u200b\u63d0\u4f9b\u200b\u4e86\u200bparse\u200b\u548c\u200bparse_config\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b\u5e76\u200b\u521b\u5efa\u200b/\u200b\u66f4\u65b0\u200bConfig\u3002
CHANfiG \u200b\u6709\u7740\u200b\u5f3a\u5927\u200b\u7684\u200b\u524d\u200b\u5411\u200b\u517c\u5bb9\u200b\u80fd\u529b\u200b\uff0c\u200b\u80fd\u591f\u200b\u826f\u597d\u200b\u7684\u200b\u517c\u5bb9\u200b\u4ee5\u5f80\u200b\u57fa\u4e8e\u200b yaml \u200b\u548c\u200b json \u200b\u7684\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u3002
\u200b\u5982\u679c\u200b\u4f60\u200b\u6b64\u524d\u200b\u4f7f\u7528\u200b yacs\uff0c\u200b\u53ea\u200b\u9700\u200b\u7b80\u5355\u200b\u5c06\u200bCfgNode\u200b\u66ff\u6362\u200b\u4e3a\u200bConfig\u200b\u4fbf\u200b\u53ef\u4ee5\u200b\u4eab\u53d7\u200b\u6240\u6709\u200b CHANfiG \u200b\u6240\u200b\u63d0\u4f9b\u200b\u7684\u200b\u4fbf\u5229\u200b\u3002
\u200b\u66f4\u8fdb\u4e00\u6b65\u200b\u7684\u200b\uff0c\u200b\u5982\u679c\u200b\u4f60\u200b\u53d1\u73b0\u200bConfig\u200b\u4e2d\u200b\u7684\u200b\u540d\u5b57\u200b\u5bf9\u4e8e\u200b\u547d\u4ee4\u884c\u200b\u6765\u8bf4\u200b\u8fc7\u957f\u200b\uff0c\u200b\u4f60\u200b\u53ef\u4ee5\u200b\u7b80\u5355\u200b\u7684\u200b\u8c03\u7528\u200bself.add_argument\u200b\u5e76\u200b\u8bbe\u7f6e\u200b\u6070\u5f53\u200b\u7684\u200bdest\u200b\u6765\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u4f7f\u7528\u200b\u66f4\u200b\u77ed\u200b\u7684\u200b\u540d\u5b57\u200b\uff0c\u200b\u6b63\u5982\u200bargparse\u200b\u6240\u200b\u505a\u200b\u7684\u200b\u90a3\u6837\u200b\u3002
from chanfig import Config, Variable\nclass Model:\ndef __init__(self, encoder, dropout=0.1, activation='ReLU'):\nself.encoder = Encoder(**encoder)\nself.dropout = Dropout(dropout)\nself.activation = getattr(Activation, activation)\ndef main(config):\nmodel = Model(**config.model)\noptimizer = Optimizer(**config.optimizer)\nscheduler = Scheduler(**config.scheduler)\ndataset = Dataset(**config.dataset)\ndataloader = Dataloader(**config.dataloader)\nclass TestConfig(Config):\ndef __init__(self):\nsuper().__init__()\ndropout = Variable(0.1)\nself.name = \"CHANfiG\"\nself.seed = 1013\nself.data.batch_size = 64\nself.model.encoder.num_layers = 6\nself.model.decoder.num_layers = 6\nself.model.dropout = dropout\nself.model.encoder.dropout = dropout\nself.model.decoder.dropout = dropout\nself.activation = \"GELU\"\nself.optim.lr = 1e-3\nself.add_argument(\"--batch_size\", dest=\"data.batch_size\")\nself.add_argument(\"--lr\", dest=\"optim.lr\")\ndef post(self):\nself.id = f\"{self.name}_{self.seed}\"\nif __name__ == '__main__':\n# config = Config.load('config.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b yaml\n# config = Config.load('config.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b json\n# existing_configs = {'data.batch_size': 64, 'model.encoder.num_layers': 8}\n# config = Config(**existing_configs) # \u200b\u5982\u679c\u200b\u4f60\u200b\u6709\u4e9b\u200bconfig\u200b\u9700\u8981\u200b\u8bfb\u53d6\u200b\nconfig = TestConfig()\nconfig = config.parse()\n# config.merge('dataset.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u5408\u5e76\u200b\u4e00\u4e2a\u200b yaml\n# config.merge('dataset.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u5408\u5e76\u200b\u4e00\u4e2a\u200b json\n# \u200b\u6ce8\u610f\u200b\u88ab\u200b\u5408\u5e76\u200b\u7684\u200b\u503c\u200b\u5177\u6709\u200b\u66f4\u200b\u9ad8\u200b\u7684\u200b\u4f18\u5148\u7ea7\u200b\nconfig.model.decoder.num_layers = 8\nconfig.freeze()\nprint(config)\n# main(config)\n# config.yaml('config.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u4fdd\u5b58\u200b\u4e00\u4e2a\u200b yaml\n# config.json('config.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u4fdd\u5b58\u200b\u4e00\u4e2a\u200b json\n\u200b\u6240\u6709\u200b\u4f60\u200b\u9700\u8981\u200b\u505a\u200b\u7684\u200b\u4ec5\u4ec5\u200b\u662f\u200b\u8fd0\u884c\u200b\u4e00\u884c\u200b\uff1a
Bashpython main.py --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\n\u200b\u5f53\u7136\u200b\uff0c\u200b\u4f60\u200b\u4e5f\u200b\u53ef\u4ee5\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b\u9ed8\u8ba4\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u7136\u540e\u200b\u5728\u200b\u4ed6\u200b\u57fa\u7840\u200b\u4e0a\u200b\u4fee\u6539\u200b\uff1a
\u200b\u6ce8\u610f\u200b\uff0c\u200b\u4f60\u200b\u5fc5\u987b\u200b\u6307\u5b9a\u200bconfig.parse(default_config='config')\u200b\u6765\u200b\u6b63\u786e\u200b\u8bfb\u53d6\u200b\u9ed8\u8ba4\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u3002
python main.py --config meow.yaml --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\n\u200b\u5982\u679c\u200b\u4f60\u200b\u4fdd\u5b58\u200b\u4e86\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u90a3\u200b\u4ed6\u200b\u5e94\u8be5\u200b\u770b\u8d77\u6765\u200b\u50cf\u200b\u8fd9\u6837\u200b\uff1a
YAMLactivation: GELU\ndata:\nbatch_size: 64\nid: CHANfiG_1013\nmodel:\ndecoder:\ndropout: 0.1\nnum_layers: 6\ndropout: 0.1\nencoder:\ndropout: 0.1\nnum_layers: 6\nname: CHANfiG\noptim:\nlr: 0.005\nseed: 1013\n{\n\"name\": \"CHANfiG\",\n\"seed\": 1013,\n\"data\": {\n\"batch_size\": 64\n},\n\"model\": {\n\"encoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"decoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"dropout\": 0.1\n},\n\"activation\": \"GELU\",\n\"optim\": {\n\"lr\": 0.005\n},\n\"id\": \"CHANfiG_1013\"\n}\n\u200b\u5728\u200b\u65b9\u6cd5\u200b\u4e2d\u200b\u5b9a\u4e49\u200b\u9ed8\u8ba4\u200b\u53c2\u6570\u200b\uff0c\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u5c06\u200b\u5269\u4e0b\u200b\u7684\u200b\u4ea4\u7ed9\u200b CHANfiG\u3002
"},{"location":"zh/#_6","title":"\u5b89\u88c5","text":"\u200b\u5b89\u88c5\u200b pypi \u200b\u4e0a\u200b\u6700\u8fd1\u200b\u7684\u200b\u7a33\u5b9a\u200b\u7248\u672c\u200b\uff1a
Bashpip install chanfig\n\u200b\u4ece\u200b\u6e90\u7801\u200b\u5b89\u88c5\u200b\u6700\u65b0\u200b\u7684\u200b\u7248\u672c\u200b\uff1a
Bashpip install git+https://github.com/ZhiyuanChen/CHANfiG\n\u200b\u4ed6\u200b\u672c\u8be5\u5982\u6b64\u200b\u5de5\u4f5c\u200b\u3002
"},{"location":"zh/#_7","title":"\u6388\u6743","text":"CHANfiG \u200b\u4f9d\u636e\u200b\u4e0b\u5217\u200b\u8bb8\u53ef\u8bc1\u200b\u8fdb\u884c\u200b\u591a\u91cd\u200b\u6388\u6743\u200b\uff1a
\u200b\u5982\u679c\u200b\u4f60\u200b\u4f7f\u7528\u200b\u672c\u200b\u5de5\u4f5c\u200b\uff0c\u200b\u4f60\u200b\u53ef\u4ee5\u200b\u4ece\u4e2d\u200b\u4efb\u9009\u200b\uff08\u200b\u4e00\u4e2a\u200b\u6216\u8005\u200b\u591a\u4e2a\u200b\uff09\u200b\u8bb8\u53ef\u8bc1\u200b\u3002
SPDX-License-Identifier: Unlicense OR AGPL-3.0-or-later OR GPL-2.0-or-later OR BSD-4-Clause OR MIT OR Apache-2.0
CHANfiG aims to make your configuration easier.
There are tons of configurable parameters in training a Machine Learning model. To configure all these parameters, researchers usually need to write gigantic config files, sometimes even thousands of lines. Most of the configs are just replicates of the default arguments of certain functions, resulting in many unnecessary declarations. It is also very hard to alter the configurations. One needs to navigate and open the right configuration file, make changes, save and exit. These had wasted an uncountable1 amount of precious time and are no doubt a crime. Using argparse could relieve the burdens to some extent. However, it takes a lot of work to make it compatible with existing config files, and its lack of nesting limits its potential.
CHANfiG would like to make a change.
You just type the alternations in the command line, and leave everything else to CHANfiG.
CHANfiG is highly inspired by YACS. Different from the paradigm of YACS( your code + a YACS config for experiment E (+ external dependencies + hardware + other nuisance terms ...) = reproducible experiment E), The paradigm of CHANfiG is:
your code + command line arguments (+ optional CHANfiG config + external dependencies + hardware + other nuisance terms ...) = reproducible experiment E (+ optional CHANfiG config for experiment E)
A Config is basically a nested dict structure.
However, the default Python dict is hard to manipulate.
The only way to access a dict member is through dict['name'], which is obviously extremely complex. Even worse, if the dict is nested like a config, member access could be something like dict['parent']['children']['name'].
Enough is enough, it is time to make a change.
We need attribute-style access, and we need it now. dict.name and dict.parent.children.name is all you need.
Although there have been some other works that achieve a similar functionality of attribute-style access to dict members. Their Config object either uses a separate dict to store information from attribute-style access (EasyDict), which may lead to inconsistency between attribute-style access and dict-style access; or re-use the existing __dict__ and redirect dict-style access (ml_collections), which may result in confliction between attributes and members of Config.
To overcome the aforementioned limitations, we inherit the Python built-in dict to create FlatDict, DefaultDict, NestedDict, Config, and Registry. We also introduce Variable to allow sharing a value across multiple places, and ConfigParser to parse command line arguments.
FlatDict improves the default dict in 3 aspects.
FlatDict incorporates a merge method that allows you to merge a Mapping, an Iterable, or a path to the FlatDict. Different from built-in update, merge assign values instead of replace, which makes it works better with DefaultDict.
dict in Python is ordered since Python 3.7, but there isn\u2019t a built-in method to help you sort a dict. FlatDictsupportssort to help you manage your dict.
Moreover, FlatDict comes with difference and intersect, which makes it very easy to compare a FlatDict with other Mapping, Iterable, or a path.
FlatDict supports to method similar to PyTorch Tensors. You can simply convert all member values of FlatDict to a certain type or pass to a device in the same way.
FlatDict also integrates cpu, gpu (cuda), and tpu (xla) methods for easier access.
FlatDict provides json, jsons, yaml and yamls methods to dump FlatDict to a file or string. It also provides from_json, from_jsons, from_yaml and from_yamls methods to build a FlatDict from a string or file.
FlatDict also includes dump and load methods which determines the type by its extension and dump/load FlatDict to/from a file.
To facility the needs of default values, we incorporate DefaultDict which accepts default_factory and works just like a collections.defaultdict.
Since most Configs are in a nested structure, we further propose a NestedDict.
Based on DefaultDict, NestedDict provides all_keys, all_values, and all_items methods to allow iterating over the whole nested structure at once.
NestedDict also comes with apply and apply_ methods, which made it easier to manipulate the nested structure.
Config extends the functionality by supporting freeze and defrost, and by adding a built-in ConfigParser to pare command line arguments.
Note that Config also has default_factory=Config() by default for convenience.
Registry extends the NestedDict and supports register, lookup, and build to help you register constructors and build objects from a Config.
Have one value for multiple names at multiple places? We got you covered.
Just wrap the value with Variable, and one alteration will be reflected everywhere.
Variable also supports type, choices, validator, and required to ensure the correctness of the value.
To make it even easier, Variable also supports help to provide a description when using ConfigParser.
ConfigParser extends ArgumentParser and provides parse and parse_config to parse command line arguments.
CHANfiG has great backward compatibility with previous configs.
No matter if your old config is json or yaml, you could directly read from them.
And if you are using yacs, just replace CfgNode with Config and enjoy all the additional benefits that CHANfiG provides.
Moreover, if you find a name in the config is too long for command-line, you could simply call self.add_argument with proper dest to use a shorter name in command-line, as you do with argparse.
from chanfig import Config, Variable\nclass Model:\ndef __init__(self, encoder, dropout=0.1, activation='ReLU'):\nself.encoder = Encoder(**encoder)\nself.dropout = Dropout(dropout)\nself.activation = getattr(Activation, activation)\ndef main(config):\nmodel = Model(**config.model)\noptimizer = Optimizer(**config.optimizer)\nscheduler = Scheduler(**config.scheduler)\ndataset = Dataset(**config.dataset)\ndataloader = Dataloader(**config.dataloader)\nclass TestConfig(Config):\ndef __init__(self):\nsuper().__init__()\ndropout = Variable(0.1)\nself.name = \"CHANfiG\"\nself.seed = 1013\nself.data.batch_size = 64\nself.model.encoder.num_layers = 6\nself.model.decoder.num_layers = 6\nself.model.dropout = dropout\nself.model.encoder.dropout = dropout\nself.model.decoder.dropout = dropout\nself.activation = \"GELU\"\nself.optim.lr = 1e-3\nself.add_argument(\"--batch_size\", dest=\"data.batch_size\")\nself.add_argument(\"--lr\", dest=\"optim.lr\")\ndef post(self):\nself.id = f\"{self.name}_{self.seed}\"\nif __name__ == '__main__':\n# config = Config.load('config.yaml') # in case you want to read from a yaml\n# config = Config.load('config.json') # in case you want to read from a json\n# existing_configs = {'data.batch_size': 64, 'model.encoder.num_layers': 8}\n# config = Config(**existing_configs) # in case you have some config in dict to load\nconfig = TestConfig()\nconfig = config.parse()\n# config.merge('dataset.yaml') # in case you want to merge a yaml\n# config.merge('dataset.json') # in case you want to merge a json\n# note that the value of merge will override current values\nconfig.model.decoder.num_layers = 8\nconfig.freeze()\nprint(config)\n# main(config)\n# config.yaml('config.yaml') # in case you want to save a yaml\n# config.json('config.json') # in case you want to save a json\nAll you need to do is just run a line:
Bashpython main.py --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\nYou could also load a default configure file and make changes based on it:
Note, you must specify config.parse(default_config='config') to correctly load the default config.
python main.py --config meow.yaml --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\nIf you have made it dump current configurations, this should be in the written file:
YAMLactivation: GELU\ndata:\nbatch_size: 64\nid: CHANfiG_1013\nmodel:\ndecoder:\ndropout: 0.1\nnum_layers: 6\ndropout: 0.1\nencoder:\ndropout: 0.1\nnum_layers: 6\nname: CHANfiG\noptim:\nlr: 0.005\nseed: 1013\n{\n\"name\": \"CHANfiG\",\n\"seed\": 1013,\n\"data\": {\n\"batch_size\": 64\n},\n\"model\": {\n\"encoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"decoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"dropout\": 0.1\n},\n\"activation\": \"GELU\",\n\"optim\": {\n\"lr\": 0.005\n},\n\"id\": \"CHANfiG_1013\"\n}\nDefine the default arguments in function, put alterations in CLI, and leave the rest to CHANfiG.
"},{"location":"#installation","title":"Installation","text":"Install the most recent stable version on pypi:
Bashpip install chanfig\nInstall the latest version from source:
Bashpip install git+https://github.com/ZhiyuanChen/CHANfiG\nIt works the way it should have worked.
"},{"location":"#license","title":"License","text":"CHANfiG is multi-licensed under the following licenses:
You can choose any (one or more) of these licenses if you use this work.
SPDX-License-Identifier: Unlicense OR AGPL-3.0-or-later OR GPL-2.0-or-later OR BSD-4-Clause OR MIT OR Apache-2.0
fun fact: time is always uncountable.\u00a0\u21a9
Config","text":" Bases: NestedDict
Config is an extension of NestedDict.
The differences between Config and NestedDict lies in 3 aspects:
Config has default_factory set to Config and convert_mapping set to True by default.Config has a frozen attribute, which can be toggled with freeze(lock) & defrost(unlock) or temporarily changed with locked & unlocked.Config has a ConfigParser built-in, and supports add_argument and parse.Config also features a post method and a boot method to support lazy-initilisation. This is useful when you want to perform some post-processing on the config. For example, some values may be a combination of other values, and you may define them in post.
boot is introduced to call all post methods in the nested structure of Config object. By default, boot will be called to after Config is parsed.
You could also manually call boot if you you don\u2019t parse command-line arguments.
Since Config has default_factory set to Config, accessing anything that does not exist will create a new empty Config sub-attribute.
A frozen Config does not have this behaviour and will raises KeyError when accessing anything that does not exist.
It is recommended to call config.freeze() or config.to(NestedDict) to avoid this behaviour.
Attributes:
Name Type Descriptionparser ConfigParser Parser for command-line arguments.
frozen bool If True, the config is frozen and cannot be altered.
Examples:
Python Console Session>>> c = Config(**{\"f.n\": \"chang\"})\n>>> c.i.d = 1013\n>>> c.i.d\n1013\n>>> c.d.i\nConfig(<class 'chanfig.config.Config'>, )\n>>> c.freeze().dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}, 'd': {'i': {}}}\n>>> c.d.i = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.d.e\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'e'\n>>> with c.unlocked():\n... del c.d\n>>> c.dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}}\nchanfig/config.py Pythonclass Config(NestedDict): # type: ignore\nr\"\"\"\n `Config` is an extension of `NestedDict`.\n The differences between `Config` and `NestedDict` lies in 3 aspects:\n 1. `Config` has `default_factory` set to `Config` and `convert_mapping` set to `True` by default.\n 2. `Config` has a `frozen` attribute, which can be toggled with `freeze`(`lock`) & `defrost`(`unlock`)\n or temporarily changed with `locked` & `unlocked`.\n 3. `Config` has a `ConfigParser` built-in, and supports `add_argument` and `parse`.\n Config also features a `post` method and a `boot` method to support lazy-initilisation.\n This is useful when you want to perform some post-processing on the config.\n For example, some values may be a combination of other values, and you may define them in `post`.\n `boot` is introduced to call all `post` methods in the nested structure of `Config` object.\n By default, `boot` will be called to after `Config` is parsed.\n You could also manually call `boot` if you you don't parse command-line arguments.\n Notes:\n Since `Config` has `default_factory` set to `Config`,\n accessing anything that does not exist will create a new empty Config sub-attribute.\n A **frozen** `Config` does not have this behaviour and\n will raises `KeyError` when accessing anything that does not exist.\n It is recommended to call `config.freeze()` or `config.to(NestedDict)` to avoid this behaviour.\n Attributes:\n parser (ConfigParser): Parser for command-line arguments.\n frozen (bool): If `True`, the config is frozen and cannot be altered.\n Examples:\n >>> c = Config(**{\"f.n\": \"chang\"})\n >>> c.i.d = 1013\n >>> c.i.d\n 1013\n >>> c.d.i\n Config(<class 'chanfig.config.Config'>, )\n >>> c.freeze().dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}, 'd': {'i': {}}}\n >>> c.d.i = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.d.e\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'e'\n >>> with c.unlocked():\n ... del c.d\n >>> c.dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}}\n \"\"\"\nparser: None # ConfigParser, Python 3.7 does not support forward reference\nfrozen: bool = False\ndef __init__(self, *args: Any, default_factory: Callable | None = None, **kwargs: Any):\nif default_factory is None:\ndefault_factory = Config\nsuper().__init__(*args, default_factory=default_factory, **kwargs)\ndef post(self) -> Config | None:\nr\"\"\"\n Post process of `Config`.\n Some `Config` may need to do some post process after `Config` is initialised.\n `post` is provided for this lazy-initialisation purpose.\n By default, `post` calls `interpolate` to perform variable interpolation.\n Note that you should always call `boot` to apply `post` rather than calling `post` directly,\n as `boot` recursively call `post` on sub-configs.\n See Also: [`boot`][chanfig.Config.boot]\n Returns:\n self:\n Examples:\n >>> class PostConfig(Config):\n ... def post(self):\n ... if isinstance(self.data, str):\n ... self.data = Config(feature=self.data, label=self.data)\n ... return self\n >>> c = PostConfig(data=\"path\")\n >>> c.post()\n PostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n \"\"\"\nself.interpolate()\nself.validate()\nreturn self\ndef boot(self) -> Config:\nr\"\"\"\n Apply `post` recursively.\n Sub-config may have their own `post` method.\n `boot` is provided to apply `post` recursively.\n By default, `boot` is called after `Config` is parsed.\n If you don't need to parse command-line arguments, you should call `boot` manually.\n See Also: [`post`][chanfig.Config.post]\n Returns:\n self:\n Examples:\n >>> class DataConfig(Config):\n ... def post(self):\n ... if isinstance(self.path, str):\n ... self.path = Config(feature=self.path, label=self.path)\n ... return self\n >>> class BootConfig(Config):\n ... def __init__(self, *args, **kwargs):\n ... super().__init__(*args, **kwargs)\n ... self.dataset = DataConfig(path=\"path\")\n ... def post(self):\n ... if isinstance(self.id, str):\n ... self.id += \"_id\"\n ... return self\n >>> c = BootConfig(id=\"boot\")\n >>> c.boot()\n BootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n )\n \"\"\"\nfor value in self.values():\nif isinstance(value, Config):\nvalue.boot()\nself.post()\nreturn self\ndef parse(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse` will try to parse all command-line arguments,\n you don't need to pre-define them but typos may cause trouble.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse`][chanfig.ConfigParser.parse]: Implementation of `parse`.\n [`parse_config`][chanfig.Config.parse_config]: Only parse valid config arguments.\n Examples:\n >>> c = Config(a=0)\n >>> c.dict()\n {'a': 0}\n >>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\ndef parse_config(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse_config` only parse command-line arguments that is in defined in `Config`.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse_config`][chanfig.ConfigParser.parse_config]: Implementation of `parse_config`.\n [`parse`][chanfig.Config.parse]: Parse all command-line arguments.\n Examples:\n >>> c = Config(a=0, b=0, c=0)\n >>> c.dict()\n {'a': 0, 'b': 0, 'c': 0}\n >>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse_config(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\ndef add_argument(self, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Add an argument to `ConfigParser`.\n Note that value defined in `Config` will override the default value defined in `add_argument`.\n Examples:\n >>> c = Config(a=0, c=1)\n >>> arg = c.add_argument(\"--a\", type=int, default=1)\n >>> arg = c.add_argument(\"--b\", type=int, default=2)\n >>> c.parse(['--c', '4']).dict()\n {'a': 1, 'c': 4, 'b': 2}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nreturn self.getattr(\"parser\").add_argument(*args, **kwargs)\ndef freeze(self, recursive: bool = True) -> Config:\nr\"\"\"\n Freeze `Config`.\n Args:\n recursive:\n **Alias**:\n + `lock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.i.getattr('frozen')\n False\n >>> c.lock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n True\n \"\"\"\n@wraps(self.freeze)\ndef freeze(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", True)\nif recursive:\nself.apply_(freeze)\nelse:\nfreeze(self)\nreturn self\ndef lock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`freeze`][chanfig.Config.freeze].\n \"\"\"\nreturn self.freeze(recursive=recursive)\n@contextmanager\ndef locked(self):\n\"\"\"\n Context manager which temporarily locks `Config`.\n Examples:\n >>> c = Config()\n >>> with c.locked():\n ... c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.i.d = 1013\n >>> c.dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.freeze()\nyield self\nfinally:\nif not was_frozen:\nself.defrost()\ndef defrost(self, recursive: bool = True) -> Config:\nr\"\"\"\n Defrost `Config`.\n Args:\n recursive:\n **Alias**:\n + `unlock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.defrost(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n False\n >>> c.i.getattr('frozen')\n True\n >>> c.unlock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n False\n \"\"\"\n@wraps(self.defrost)\ndef defrost(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", False)\nif recursive:\nself.apply_(defrost)\nelse:\ndefrost(self)\nreturn self\ndef unlock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`defrost`][chanfig.Config.defrost].\n \"\"\"\nreturn self.defrost(recursive=recursive)\n@contextmanager\ndef unlocked(self):\n\"\"\"\n Context manager which temporarily unlocks `Config`.\n Examples:\n >>> c = Config()\n >>> c.freeze().dict()\n {}\n >>> with c.unlocked():\n ... c['i.d'] = 1013\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.defrost()\nyield self\nfinally:\nif was_frozen:\nself.freeze()\ndef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `Config`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `Config` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `Config` does not contain `name` and `default`/`default_factory` is not specified.\n Examples:\n >>> d = Config(**{\"i.d\": 1013})\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.f\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.f\n >>> d.freeze()\n Config(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n )\n >>> d.f\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'f'\n >>> d[\"f.n\"]\n Traceback (most recent call last):\n KeyError: 'f.n'\n \"\"\"\nif not self.hasattr(\"default_factory\"): # did not call super().__init__() in sub-class\nself.setattr(\"default_factory\", Config)\nif name in self or not self.getattr(\"frozen\", False):\nreturn super().get(name, default, fallback)\nraise KeyError(name)\n@frozen_check\ndef set(\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `Config`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Raises:\n ValueError: If `Config` is frozen.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n \"\"\"\nreturn super().set(name, value, convert_mapping)\n@frozen_check\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `Config`.\n Args:\n name:\n Examples:\n >>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> \"i.d\" in d\n False\n >>> d.i.d\n Config(<class 'chanfig.config.Config'>, )\n >>> \"i.d\" in d\n True\n >>> del d.f.n\n >>> d.f.n\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.c\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'c'\n \"\"\"\nsuper().delete(name)\n@frozen_check\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `Config`.\n Args:\n name:\n default:\n Returns:\n value: If `Config` does not contain `name`, return `default`.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n >>> c.pop('i.d', True)\n True\n >>> c.freeze().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n \"\"\"\nreturn super().pop(name, default)\nadd_argument(*args, **kwargs)","text":"Add an argument to ConfigParser.
Note that value defined in Config will override the default value defined in add_argument.
Examples:
Python Console Session>>> c = Config(a=0, c=1)\n>>> arg = c.add_argument(\"--a\", type=int, default=1)\n>>> arg = c.add_argument(\"--b\", type=int, default=2)\n>>> c.parse(['--c', '4']).dict()\n{'a': 1, 'c': 4, 'b': 2}\nchanfig/config.py Pythondef add_argument(self, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Add an argument to `ConfigParser`.\n Note that value defined in `Config` will override the default value defined in `add_argument`.\n Examples:\n >>> c = Config(a=0, c=1)\n >>> arg = c.add_argument(\"--a\", type=int, default=1)\n >>> arg = c.add_argument(\"--b\", type=int, default=2)\n >>> c.parse(['--c', '4']).dict()\n {'a': 1, 'c': 4, 'b': 2}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nreturn self.getattr(\"parser\").add_argument(*args, **kwargs)\nboot()","text":"Apply post recursively.
Sub-config may have their own post method. boot is provided to apply post recursively.
By default, boot is called after Config is parsed. If you don\u2019t need to parse command-line arguments, you should call boot manually.
See Also: post
Returns:
Name Type Descriptionself Config Examples:
Python Console Session>>> class DataConfig(Config):\n... def post(self):\n... if isinstance(self.path, str):\n... self.path = Config(feature=self.path, label=self.path)\n... return self\n>>> class BootConfig(Config):\n... def __init__(self, *args, **kwargs):\n... super().__init__(*args, **kwargs)\n... self.dataset = DataConfig(path=\"path\")\n... def post(self):\n... if isinstance(self.id, str):\n... self.id += \"_id\"\n... return self\n>>> c = BootConfig(id=\"boot\")\n>>> c.boot()\nBootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n)\nchanfig/config.py Pythondef boot(self) -> Config:\nr\"\"\"\n Apply `post` recursively.\n Sub-config may have their own `post` method.\n `boot` is provided to apply `post` recursively.\n By default, `boot` is called after `Config` is parsed.\n If you don't need to parse command-line arguments, you should call `boot` manually.\n See Also: [`post`][chanfig.Config.post]\n Returns:\n self:\n Examples:\n >>> class DataConfig(Config):\n ... def post(self):\n ... if isinstance(self.path, str):\n ... self.path = Config(feature=self.path, label=self.path)\n ... return self\n >>> class BootConfig(Config):\n ... def __init__(self, *args, **kwargs):\n ... super().__init__(*args, **kwargs)\n ... self.dataset = DataConfig(path=\"path\")\n ... def post(self):\n ... if isinstance(self.id, str):\n ... self.id += \"_id\"\n ... return self\n >>> c = BootConfig(id=\"boot\")\n >>> c.boot()\n BootConfig(<class 'chanfig.config.Config'>,\n ('id'): 'boot_id'\n ('dataset'): DataConfig(<class 'chanfig.config.Config'>,\n ('path'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n )\n \"\"\"\nfor value in self.values():\nif isinstance(value, Config):\nvalue.boot()\nself.post()\nreturn self\ndefrost(recursive=True)","text":"Defrost Config.
Parameters:
Name Type Description Defaultrecursive bool True Alias:
unlockExamples:
Python Console Session>>> c = Config(**{'i.d': 1013})\n>>> c.getattr('frozen')\nFalse\n>>> c.freeze().dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nTrue\n>>> c.defrost(recursive=False).dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nFalse\n>>> c.i.getattr('frozen')\nTrue\n>>> c.unlock().dict() # alias\n{'i': {'d': 1013}}\n>>> c.i.getattr('frozen')\nFalse\nchanfig/config.py Pythondef defrost(self, recursive: bool = True) -> Config:\nr\"\"\"\n Defrost `Config`.\n Args:\n recursive:\n **Alias**:\n + `unlock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.defrost(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n False\n >>> c.i.getattr('frozen')\n True\n >>> c.unlock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n False\n \"\"\"\n@wraps(self.defrost)\ndef defrost(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", False)\nif recursive:\nself.apply_(defrost)\nelse:\ndefrost(self)\nreturn self\ndelete(name)","text":"Delete value from Config.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n>>> d.i.d\n1013\n>>> d.f.n\n'chang'\n>>> d.delete('i.d')\n>>> \"i.d\" in d\nFalse\n>>> d.i.d\nConfig(<class 'chanfig.config.Config'>, )\n>>> \"i.d\" in d\nTrue\n>>> del d.f.n\n>>> d.f.n\nConfig(<class 'chanfig.config.Config'>, )\n>>> del d.c\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'c'\nchanfig/config.py Python@frozen_check\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `Config`.\n Args:\n name:\n Examples:\n >>> d = Config(**{\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> \"i.d\" in d\n False\n >>> d.i.d\n Config(<class 'chanfig.config.Config'>, )\n >>> \"i.d\" in d\n True\n >>> del d.f.n\n >>> d.f.n\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.c\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'c'\n \"\"\"\nsuper().delete(name)\nfreeze(recursive=True)","text":"Freeze Config.
Parameters:
Name Type Description Defaultrecursive bool True Alias:
lockExamples:
Python Console Session>>> c = Config(**{'i.d': 1013})\n>>> c.getattr('frozen')\nFalse\n>>> c.freeze(recursive=False).dict()\n{'i': {'d': 1013}}\n>>> c.getattr('frozen')\nTrue\n>>> c.i.getattr('frozen')\nFalse\n>>> c.lock().dict() # alias\n{'i': {'d': 1013}}\n>>> c.i.getattr('frozen')\nTrue\nchanfig/config.py Pythondef freeze(self, recursive: bool = True) -> Config:\nr\"\"\"\n Freeze `Config`.\n Args:\n recursive:\n **Alias**:\n + `lock`\n Examples:\n >>> c = Config(**{'i.d': 1013})\n >>> c.getattr('frozen')\n False\n >>> c.freeze(recursive=False).dict()\n {'i': {'d': 1013}}\n >>> c.getattr('frozen')\n True\n >>> c.i.getattr('frozen')\n False\n >>> c.lock().dict() # alias\n {'i': {'d': 1013}}\n >>> c.i.getattr('frozen')\n True\n \"\"\"\n@wraps(self.freeze)\ndef freeze(config: Config) -> None:\nif isinstance(config, Config):\nconfig.setattr(\"frozen\", True)\nif recursive:\nself.apply_(freeze)\nelse:\nfreeze(self)\nreturn self\nget(name, default=None, fallback=None)","text":"Get value from Config.
Note that default has higher priority than default_factory.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If Config does not contain name, return default. If default is not specified, return default_factory().
Raises:
Type DescriptionKeyError If Config does not contain name and default/default_factory is not specified.
Examples:
Python Console Session>>> d = Config(**{\"i.d\": 1013})\n>>> d.get('i.d')\n1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.get('f', 2)\n2\n>>> d.f\nConfig(<class 'chanfig.config.Config'>, )\n>>> del d.f\n>>> d.freeze()\nConfig(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n)\n>>> d.f\nTraceback (most recent call last):\nAttributeError: 'Config' object has no attribute 'f'\n>>> d[\"f.n\"]\nTraceback (most recent call last):\nKeyError: 'f.n'\nchanfig/config.py Pythondef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `Config`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `Config` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `Config` does not contain `name` and `default`/`default_factory` is not specified.\n Examples:\n >>> d = Config(**{\"i.d\": 1013})\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.f\n Config(<class 'chanfig.config.Config'>, )\n >>> del d.f\n >>> d.freeze()\n Config(<class 'chanfig.config.Config'>,\n ('i'): Config(<class 'chanfig.config.Config'>,\n ('d'): 1013\n )\n )\n >>> d.f\n Traceback (most recent call last):\n AttributeError: 'Config' object has no attribute 'f'\n >>> d[\"f.n\"]\n Traceback (most recent call last):\n KeyError: 'f.n'\n \"\"\"\nif not self.hasattr(\"default_factory\"): # did not call super().__init__() in sub-class\nself.setattr(\"default_factory\", Config)\nif name in self or not self.getattr(\"frozen\", False):\nreturn super().get(name, default, fallback)\nraise KeyError(name)\nlock(recursive=True)","text":"Alias of freeze.
chanfig/config.py Pythondef lock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`freeze`][chanfig.Config.freeze].\n \"\"\"\nreturn self.freeze(recursive=recursive)\nlocked()","text":"Context manager which temporarily locks Config.
Examples:
Python Console Session>>> c = Config()\n>>> with c.locked():\n... c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.i.d = 1013\n>>> c.dict()\n{'i': {'d': 1013}}\nchanfig/config.py Python@contextmanager\ndef locked(self):\n\"\"\"\n Context manager which temporarily locks `Config`.\n Examples:\n >>> c = Config()\n >>> with c.locked():\n ... c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.i.d = 1013\n >>> c.dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.freeze()\nyield self\nfinally:\nif not was_frozen:\nself.defrost()\nparse(args=None, default_config=None, no_default_config_action='raise', boot=True)","text":"Parse command-line arguments with ConfigParser.
parse will try to parse all command-line arguments, you don\u2019t need to pre-define them but typos may cause trouble.
By default, this method internally calls Config.boot(). To disable this behaviour, set boot to False.
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to None.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' boot bool If True, call Config.boot() after parsing. Defaults to True.
True See Also chanfig.ConfigParser.parse: Implementation of parse. parse_config: Only parse valid config arguments.
Examples:
Python Console Session>>> c = Config(a=0)\n>>> c.dict()\n{'a': 0}\n>>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/config.py Pythondef parse(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse` will try to parse all command-line arguments,\n you don't need to pre-define them but typos may cause trouble.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse`][chanfig.ConfigParser.parse]: Implementation of `parse`.\n [`parse_config`][chanfig.Config.parse_config]: Only parse valid config arguments.\n Examples:\n >>> c = Config(a=0)\n >>> c.dict()\n {'a': 0}\n >>> c.parse(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\nparse_config(args=None, default_config=None, no_default_config_action='raise', boot=True)","text":"Parse command-line arguments with ConfigParser.
parse_config only parse command-line arguments that is in defined in Config.
By default, this method internally calls Config.boot(). To disable this behaviour, set boot to False.
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to None.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' boot bool If True, call Config.boot() after parsing. Defaults to True.
True See Also chanfig.ConfigParser.parse_config: Implementation of parse_config. parse: Parse all command-line arguments.
Examples:
Python Console Session>>> c = Config(a=0, b=0, c=0)\n>>> c.dict()\n{'a': 0, 'b': 0, 'c': 0}\n>>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/config.py Pythondef parse_config(\nself,\nargs: Iterable[str] | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\nboot: bool = True,\n) -> Config:\nr\"\"\"\n Parse command-line arguments with `ConfigParser`.\n `parse_config` only parse command-line arguments that is in defined in `Config`.\n By default, this method internally calls `Config.boot()`.\n To disable this behaviour, set `boot` to `False`.\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `None`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n boot (bool, optional): If `True`, call `Config.boot()` after parsing. Defaults to `True`.\n See Also:\n [`chanfig.ConfigParser.parse_config`][chanfig.ConfigParser.parse_config]: Implementation of `parse_config`.\n [`parse`][chanfig.Config.parse]: Parse all command-line arguments.\n Examples:\n >>> c = Config(a=0, b=0, c=0)\n >>> c.dict()\n {'a': 0, 'b': 0, 'c': 0}\n >>> c.parse_config(['--a', '1', '--b', '2', '--c', '3']).dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nif not self.hasattr(\"parser\"):\nself.setattr(\"parser\", ConfigParser())\nself.getattr(\"parser\").parse_config(args, self, default_config, no_default_config_action)\nif boot:\nself.boot()\nreturn self\npop(name, default=Null)","text":"Pop value from Config.
Parameters:
Name Type Description Defaultname Any required default Any Null Returns:
Name Type Descriptionvalue Any If Config does not contain name, return default.
Examples:
Python Console Session>>> c = Config()\n>>> c['i.d'] = 1013\n>>> c.pop('i.d')\n1013\n>>> c.pop('i.d', True)\nTrue\n>>> c.freeze().dict()\n{'i': {}}\n>>> c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.defrost().dict()\n{'i': {}}\n>>> c['i.d'] = 1013\n>>> c.pop('i.d')\n1013\nchanfig/config.py Python@frozen_check\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `Config`.\n Args:\n name:\n default:\n Returns:\n value: If `Config` does not contain `name`, return `default`.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n >>> c.pop('i.d', True)\n True\n >>> c.freeze().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {}}\n >>> c['i.d'] = 1013\n >>> c.pop('i.d')\n 1013\n \"\"\"\nreturn super().pop(name, default)\npost()","text":"Post process of Config.
Some Config may need to do some post process after Config is initialised. post is provided for this lazy-initialisation purpose.
By default, post calls interpolate to perform variable interpolation.
Note that you should always call boot to apply post rather than calling post directly, as boot recursively call post on sub-configs.
See Also: boot
Returns:
Name Type Descriptionself Config | None Examples:
Python Console Session>>> class PostConfig(Config):\n... def post(self):\n... if isinstance(self.data, str):\n... self.data = Config(feature=self.data, label=self.data)\n... return self\n>>> c = PostConfig(data=\"path\")\n>>> c.post()\nPostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n)\nchanfig/config.py Pythondef post(self) -> Config | None:\nr\"\"\"\n Post process of `Config`.\n Some `Config` may need to do some post process after `Config` is initialised.\n `post` is provided for this lazy-initialisation purpose.\n By default, `post` calls `interpolate` to perform variable interpolation.\n Note that you should always call `boot` to apply `post` rather than calling `post` directly,\n as `boot` recursively call `post` on sub-configs.\n See Also: [`boot`][chanfig.Config.boot]\n Returns:\n self:\n Examples:\n >>> class PostConfig(Config):\n ... def post(self):\n ... if isinstance(self.data, str):\n ... self.data = Config(feature=self.data, label=self.data)\n ... return self\n >>> c = PostConfig(data=\"path\")\n >>> c.post()\n PostConfig(<class 'chanfig.config.Config'>,\n ('data'): Config(<class 'chanfig.config.Config'>,\n ('feature'): 'path'\n ('label'): 'path'\n )\n )\n \"\"\"\nself.interpolate()\nself.validate()\nreturn self\nset(name, value, convert_mapping=None)","text":"Set value of Config.
Parameters:
Name Type Description Defaultname Any required value Any required convert_mapping bool | None Whether to convert Mapping to NestedDict. Defaults to self.convert_mapping.
None Raises:
Type DescriptionValueError If Config is frozen.
Examples:
Python Console Session>>> c = Config()\n>>> c['i.d'] = 1013\n>>> c.i.d\n1013\n>>> c.freeze().dict()\n{'i': {'d': 1013}}\n>>> c['i.d'] = 1013\nTraceback (most recent call last):\nValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n>>> c.defrost().dict()\n{'i': {'d': 1013}}\n>>> c['i.d'] = 1013\n>>> c.i.d\n1013\nchanfig/config.py Python@frozen_check\ndef set(\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `Config`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Raises:\n ValueError: If `Config` is frozen.\n Examples:\n >>> c = Config()\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n >>> c.freeze().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n Traceback (most recent call last):\n ValueError: Attempting to alter a frozen config. Run config.defrost() to defrost first.\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n >>> c['i.d'] = 1013\n >>> c.i.d\n 1013\n \"\"\"\nreturn super().set(name, value, convert_mapping)\nunlock(recursive=True)","text":"Alias of defrost.
chanfig/config.py Pythondef unlock(self, recursive: bool = True) -> Config:\nr\"\"\"\n Alias of [`defrost`][chanfig.Config.defrost].\n \"\"\"\nreturn self.defrost(recursive=recursive)\nunlocked()","text":"Context manager which temporarily unlocks Config.
Examples:
Python Console Session>>> c = Config()\n>>> c.freeze().dict()\n{}\n>>> with c.unlocked():\n... c['i.d'] = 1013\n>>> c.defrost().dict()\n{'i': {'d': 1013}}\nchanfig/config.py Python@contextmanager\ndef unlocked(self):\n\"\"\"\n Context manager which temporarily unlocks `Config`.\n Examples:\n >>> c = Config()\n >>> c.freeze().dict()\n {}\n >>> with c.unlocked():\n ... c['i.d'] = 1013\n >>> c.defrost().dict()\n {'i': {'d': 1013}}\n \"\"\"\nwas_frozen = self.getattr(\"frozen\", False)\ntry:\nself.defrost()\nyield self\nfinally:\nif was_frozen:\nself.freeze()\nfrozen_check(func)","text":"Decorator check if the object is frozen.
Source code inchanfig/config.py Pythondef frozen_check(func: Callable):\nr\"\"\"\n Decorator check if the object is frozen.\n \"\"\"\n@wraps(func)\ndef decorator(self, *args: Any, **kwargs: Any):\nif self.getattr(\"frozen\", False):\nraise ValueError(\"Attempting to alter a frozen config. Run config.defrost() to defrost first.\")\nreturn func(self, *args, **kwargs)\nreturn decorator\n Bases: FlatDict
DefaultDict inherits from FlatDict and incorporates support of default_factory in the same manner as collections.defaultdict. If default_factory is not None, the value will be set to default_factory() when you access a key that does not exist in DefaultDict.
You may specify DefaultDict(default_factory=FlatDict) when creating DefaultDict or by calling dict.setattr('default_factory', FlatDict) for existing DefaultDict objects.
Note that just like collections.defaultdict, default_factory() is called without any arguments.
Attributes:
Name Type Descriptiondefault_factory Optional[Callable] Default factory for defaultdict behaviour.
Raises:
Type DescriptionTypeError If default_factory is not callable.
Unlike collections.defaultdict, DefaultDict will not automatically create entries when name starts and ends with __. This is to avoid conflicts with Python magic methods. You can still creates them manually with DefaultDict.fromkeys or DefaultDict.add.
Examples:
Python Console Session>>> d = DefaultDict(list)\n>>> d.a.append(1)\n>>> d.a\n[1]\n>>> d = DefaultDict([])\nTraceback (most recent call last):\nTypeError: `default_factory=[]` must be Callable, but got <class 'list'>.\nchanfig/default_dict.py Pythonclass DefaultDict(FlatDict): # type: ignore\nr\"\"\"\n `DefaultDict` inherits from `FlatDict` and incorporates support of `default_factory`\n in the same manner as `collections.defaultdict`.\n If `default_factory is not None`, the value will be set to `default_factory()`\n when you access a key that does not exist in `DefaultDict`.\n You may specify `DefaultDict(default_factory=FlatDict)` when creating `DefaultDict` or\n by calling `dict.setattr('default_factory', FlatDict)` for existing `DefaultDict` objects.\n Note that just like `collections.defaultdict`, `default_factory()` is called without any arguments.\n Attributes:\n default_factory: Default factory for defaultdict behaviour.\n Raises:\n TypeError: If `default_factory` is not callable.\n Notes:\n Unlike `collections.defaultdict`, `DefaultDict` will not automatically create entries when name starts and ends\n with `__`. This is to avoid conflicts with Python magic methods.\n You can still creates them manually with `DefaultDict.fromkeys` or `DefaultDict.add`.\n Examples:\n >>> d = DefaultDict(list)\n >>> d.a.append(1)\n >>> d.a\n [1]\n >>> d = DefaultDict([])\n Traceback (most recent call last):\n TypeError: `default_factory=[]` must be Callable, but got <class 'list'>.\n \"\"\"\ndefault_factory: Optional[Callable] = None\ndef __init__( # pylint: disable=W1113\nself, default_factory: Callable | None = None, *args: Any, **kwargs: Any\n) -> None:\nsuper().__init__(*args, **kwargs)\nif default_factory is not None:\nif callable(default_factory):\nself.setattr(\"default_factory\", default_factory)\nelse:\nraise TypeError(\nf\"`default_factory={default_factory}` must be Callable, but got {type(default_factory)}.\"\n)\ndef __missing__(self, name: Any, default=Null) -> Any: # pylint: disable=R1710\nif default is Null:\nif self.getattr(\"default_factory\", None) in (None, Null) or (name.startswith(\"__\") and name.endswith(\"__\")):\nraise KeyError(name) from None\ndefault = self.getattr(\"default_factory\")()\nif isinstance(default, FlatDict):\ndefault.__dict__.update(self.__dict__)\nsuper().set(name, default)\nreturn default\ndef __repr__(self) -> str:\nif self.default_factory is None:\nreturn super().__repr__()\nsuper_repr = super().__repr__()[len(self.__class__.__name__) :] # noqa: E203\nif len(super_repr) == 2:\nreturn f\"{self.__class__.__name__}({self.default_factory}, )\"\nreturn f\"{self.__class__.__name__}({self.default_factory},\" + super_repr[1:]\ndef add(self, name: Any):\nr\"\"\"\n Add a new default factory to the dictionary.\n Args:\n name:\n Raises:\n ValueError: If `default_factory` is None.\n Examples:\n >>> d = DefaultDict(default_factory=DefaultDict)\n >>> d.add('d')\n DefaultDict()\n >>> d.get('d')\n DefaultDict()\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n >>> d = DefaultDict()\n >>> d.add('a')\n Traceback (most recent call last):\n ValueError: Cannot add to a DefaultDict with no default_factory\n \"\"\"\nif self.default_factory is None:\nraise ValueError(\"Cannot add to a DefaultDict with no default_factory\")\nself.set(name, self.default_factory()) # pylint: disable=E1102\nreturn self.get(name)\nadd(name)","text":"Add a new default factory to the dictionary.
Parameters:
Name Type Description Defaultname Any required Raises:
Type DescriptionValueError If default_factory is None.
Examples:
Python Console Session>>> d = DefaultDict(default_factory=DefaultDict)\n>>> d.add('d')\nDefaultDict()\n>>> d.get('d')\nDefaultDict()\n>>> d['n'] = 'chang'\n>>> d.n\n'chang'\n>>> d.n = 'liu'\n>>> d['n']\n'liu'\n>>> d = DefaultDict()\n>>> d.add('a')\nTraceback (most recent call last):\nValueError: Cannot add to a DefaultDict with no default_factory\nchanfig/default_dict.py Pythondef add(self, name: Any):\nr\"\"\"\n Add a new default factory to the dictionary.\n Args:\n name:\n Raises:\n ValueError: If `default_factory` is None.\n Examples:\n >>> d = DefaultDict(default_factory=DefaultDict)\n >>> d.add('d')\n DefaultDict()\n >>> d.get('d')\n DefaultDict()\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n >>> d = DefaultDict()\n >>> d.add('a')\n Traceback (most recent call last):\n ValueError: Cannot add to a DefaultDict with no default_factory\n \"\"\"\nif self.default_factory is None:\nraise ValueError(\"Cannot add to a DefaultDict with no default_factory\")\nself.set(name, self.default_factory()) # pylint: disable=E1102\nreturn self.get(name)\n Bases: dict
FlatDict with attribute-style access.
FlatDict inherits from built-in dict.
It comes with many easy to use helper methods, such as merge, sort, difference, intersect.
It also has full support for IO operations, such as json and yaml.
Even better, FlatDict has pytorch support built-in. You can directly call FlatDict.cpu() or FlatDict.to(\"cpu\") to move all torch.Tensor objects across devices.
FlatDict works best with Variable objects. Simply call flat_dict.a = Variable(1); flat_dict.b = flat_dict.a, and their values will be synced.
Even better, FlatDict support variable interpolation. Just set the value of one key to another key (surrounded by braces with $ at the begin, like ${xxx}), and calls flat_dict.interpolate(), FlatDict will interpolate their values and create Variable automatically.
FlatDict has many other easy to use helper methods, such as difference, intersect. And has full support for IO operations, such as json and yaml.
FlatDict also has pytorch support built-in. You can directly call flat_dict.cpu() or flat_dict.to(\"cpu\") to move all torch.Tensor objects across devices.
Attributes:
Name Type Descriptionindent int Indentation level in printing and dumping to json or yaml.
NotesFlatDict rewrite __getattribute__ and __getattr__ to supports attribute-style access to its members. Therefore, all internal attributes should be set and get through flat_dict.setattr and flat_dict.getattr.
Although it is possible to override other internal methods, it is not recommended to do so.
__class__, __dict__, and getattr are reserved and cannot be overrode in any manner.
Examples:
Python Console Session>>> d = FlatDict()\n>>> d.d = 1013\n>>> d['d']\n1013\n>>> d['i'] = 1013\n>>> d.i\n1013\n>>> d.a = Variable(1)\n>>> d.b = d.a\n>>> d.a, d.b\n(1, 1)\n>>> d.a += 1\n>>> d.a, d.b\n(2, 2)\n>>> d.a = 3\n>>> d.a, d.b\n(3, 3)\n>>> d.a = Variable('hello')\n>>> f\"{d.a}, world!\"\n'hello, world!'\n>>> d.a = d.a + ', world!'\n>>> d.b\n'hello, world!'\nchanfig/flat_dict.py Pythonclass FlatDict(dict, metaclass=Dict): # type: ignore\nr\"\"\"\n `FlatDict` with attribute-style access.\n `FlatDict` inherits from built-in `dict`.\n It comes with many easy to use helper methods, such as `merge`, `sort`, `difference`, `intersect`.\n It also has full support for IO operations, such as `json` and `yaml`.\n Even better, `FlatDict` has pytorch support built-in.\n You can directly call `FlatDict.cpu()` or `FlatDict.to(\"cpu\")` to move all `torch.Tensor` objects across devices.\n `FlatDict` works best with `Variable` objects.\n Simply call `flat_dict.a = Variable(1); flat_dict.b = flat_dict.a`, and their values will be synced.\n Even better, `FlatDict` support variable interpolation.\n Just set the value of one key to another key (surrounded by braces with $ at the begin, like ${xxx}),\n and calls `flat_dict.interpolate()`, `FlatDict` will interpolate their values and create `Variable` automatically.\n `FlatDict` has many other easy to use helper methods, such as `difference`, `intersect`.\n And has full support for IO operations, such as `json` and `yaml`.\n `FlatDict` also has pytorch support built-in.\n You can directly call `flat_dict.cpu()` or `flat_dict.to(\"cpu\")` to move all `torch.Tensor` objects across devices.\n Attributes:\n indent: Indentation level in printing and dumping to json or yaml.\n Notes:\n `FlatDict` rewrite `__getattribute__` and `__getattr__` to supports attribute-style access to its members.\n Therefore, all internal attributes should be set and get through `flat_dict.setattr` and `flat_dict.getattr`.\n Although it is possible to override other internal methods, it is not recommended to do so.\n `__class__`, `__dict__`, and `getattr` are reserved and cannot be overrode in any manner.\n Examples:\n >>> d = FlatDict()\n >>> d.d = 1013\n >>> d['d']\n 1013\n >>> d['i'] = 1013\n >>> d.i\n 1013\n >>> d.a = Variable(1)\n >>> d.b = d.a\n >>> d.a, d.b\n (1, 1)\n >>> d.a += 1\n >>> d.a, d.b\n (2, 2)\n >>> d.a = 3\n >>> d.a, d.b\n (3, 3)\n >>> d.a = Variable('hello')\n >>> f\"{d.a}, world!\"\n 'hello, world!'\n >>> d.a = d.a + ', world!'\n >>> d.b\n 'hello, world!'\n \"\"\"\n# pylint: disable=R0904\nindent: int = 2\ndef __post_init__(self, *args, **kwargs) -> None:\npass\ndef __getattribute__(self, name: Any) -> Any:\nif (name not in (\"getattr\",) and not (name.startswith(\"__\") and name.endswith(\"__\"))) and name in self:\nreturn self.get(name)\nreturn super().__getattribute__(name)\ndef get(self, name: Any, default: Any = None) -> Any:\nr\"\"\"\n Get value from `FlatDict`.\n Args:\n name:\n default:\n Returns:\n value:\n If `FlatDict` does not contain `name`, return `default`.\n Raises:\n KeyError: If `FlatDict` does not contain `name` and `default` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = FlatDict(d=1013)\n >>> d.get('d')\n 1013\n >>> d['d']\n 1013\n >>> d.d\n 1013\n >>> d.get('d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('f')\n >>> d.get('f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\nif name in self:\nreturn dict.__getitem__(self, name)\nif default is not Null:\nreturn default\nreturn self.__missing__(name)\ndef __getitem__(self, name: Any) -> Any:\nreturn self.get(name, default=Null)\ndef __getattr__(self, name: Any) -> Any:\ntry:\nreturn self.get(name, default=Null)\nexcept KeyError:\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef set(self, name: Any, value: Any) -> None:\nr\"\"\"\n Set value of `FlatDict`.\n Args:\n name:\n value:\n Examples:\n >>> d = FlatDict()\n >>> d.set('d', 1013)\n >>> d.get('d')\n 1013\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n \"\"\"\nif name in self and isinstance(self.get(name), Variable):\nself.get(name).set(value)\nelse:\ndict.__setitem__(self, name, value)\ndef __setitem__(self, name: Any, value: Any) -> None:\nself.set(name, value)\ndef __setattr__(self, name: Any, value: Any) -> None:\nself.set(name, value)\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict(d=1016, n='chang')\n >>> d.d\n 1016\n >>> d.n\n 'chang'\n >>> d.delete('d')\n >>> d.d\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'd'\n >>> del d.n\n >>> d.n\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'n'\n >>> del d.f\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'f'\n \"\"\"\ndict.__delitem__(self, name)\ndef __delitem__(self, name: Any) -> None:\nreturn self.delete(name)\ndef __delattr__(self, name: Any) -> None:\ntry:\nself.delete(name)\nexcept KeyError:\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef __missing__(self, name: Any) -> Any: # pylint: disable=R1710\nraise KeyError(name)\ndef validate(self) -> None:\nr\"\"\"\n Validate `FlatDict`.\n Raises:\n TypeError: If value is not of the type declared in class annotations.\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n >>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\n Traceback (most recent call last):\n ValueError: 'n' has invalid value. Value chang is not valid.\n \"\"\"\nself._validate(self)\n@staticmethod\ndef _validate(obj) -> None:\nif isinstance(obj, FlatDict):\nannotations = get_annotations(obj)\nfor name, value in obj.items():\nif annotations and name in annotations and not isvalid(value, annotations[name]):\nraise TypeError(f\"'{name}' has invalid type. Value {value} is not of type {annotations[name]}.\")\nif isinstance(value, Variable):\ntry:\nvalue.validate()\nexcept TypeError as exc:\nraise TypeError(f\"'{name}' has invalid type. {exc}\") from None\nexcept ValueError as exc:\nraise ValueError(f\"'{name}' has invalid value. {exc}\") from None\ndef getattr(self, name: str, default: Any = Null) -> Any:\nr\"\"\"\n Get attribute of `FlatDict`.\n Note that it won't retrieve value in `FlatDict`,\n Args:\n name:\n default:\n Returns:\n value: If `FlatDict` does not contain `name`, return `default`.\n Raises:\n AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.\n Examples:\n >>> d = FlatDict(a=1)\n >>> d.get('a')\n 1\n >>> d.getattr('a')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'a'\n >>> d.getattr('b', 2)\n 2\n >>> d.setattr('b', 3)\n >>> d.getattr('b')\n 3\n \"\"\"\ntry:\nif name in self.__dict__:\nreturn self.__dict__[name]\nif name in self.__class__.__dict__:\nreturn self.__class__.__dict__[name]\nreturn super().getattr(name, default) # type: ignore\nexcept AttributeError:\nif default is not Null:\nreturn default\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ndef setattr(self, name: str, value: Any) -> None:\nr\"\"\"\n Set attribute of `FlatDict`.\n Note that it won't alter values in `FlatDict`.\n Args:\n name:\n value:\n Warns:\n RuntimeWarning: If name already exists in `FlatDict`.\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('attr', 'value')\n >>> d.getattr('attr')\n 'value'\n >>> d.set('d', 1013)\n >>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n >>> d.get('d')\n 1013\n >>> d.d\n 1013\n >>> d.getattr('d')\n 1031\n \"\"\"\nif name in self:\nwarn(\nf\"{name} already exists in {self.__class__.__name__}.\\n\"\nf\"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.\",\nRuntimeWarning,\n)\nself.__dict__[name] = value\ndef delattr(self, name: str) -> None:\nr\"\"\"\n Delete attribute of `FlatDict`.\n Note that it won't delete values in `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.getattr('name')\n 'chang'\n >>> d.delattr('name')\n >>> d.getattr('name')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'name'\n \"\"\"\ndel self.__dict__[name]\ndef hasattr(self, name: str) -> bool:\nr\"\"\"\n Determine if an attribute exists in `FlatDict`.\n Args:\n name:\n Returns:\n (bool):\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.hasattr('name')\n True\n >>> d.delattr('name')\n >>> d.hasattr('name')\n False\n \"\"\"\ntry:\nif name in self.__dict__ or name in self.__class__.__dict__:\nreturn True\nreturn super().hasattr(name) # type: ignore\nexcept AttributeError:\nreturn False\ndef dict(self, cls: Callable = dict) -> Mapping:\nr\"\"\"\n Convert `FlatDict` to other `Mapping`.\n Args:\n cls: Target class to be converted to.\n Returns:\n (Mapping):\n See Also:\n [`to_dict`][chanfig.flat_dict.to_dict]: Implementation of `dict`.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn cls(to_dict(self))\n@classmethod\ndef from_dict(cls, obj: Mapping | Sequence) -> Any: # pylint: disable=R0911\nr\"\"\"\n Convert `Mapping` or `Sequence` to `FlatDict`.\n Examples:\n >>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n >>> FlatDict.from_dict({1, 2, 3})\n Traceback (most recent call last):\n TypeError: Expected Mapping or Sequence, but got <class 'set'>.\n \"\"\"\nif obj is None:\nreturn cls()\nif issubclass(cls, FlatDict):\ncls = cls.empty # type: ignore # pylint: disable=W0642\nif isinstance(obj, Mapping):\nreturn cls(obj)\nif isinstance(obj, Sequence):\ntry:\nreturn cls(obj)\nexcept ValueError:\nreturn [cls(json) for json in obj]\nraise TypeError(f\"Expected Mapping or Sequence, but got {type(obj)}.\")\ndef sort(self, key: Callable | None = None, reverse: bool = False) -> FlatDict:\nr\"\"\"\n Sort `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d = FlatDict(b=2, c=3, a=1)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> a = [1]\n >>> d = FlatDict(z=0, a=a)\n >>> a.append(2)\n >>> d.sort().dict()\n {'a': [1, 2], 'z': 0}\n \"\"\"\nitems = sorted(self.items(), key=key, reverse=reverse)\nself.clear()\nfor k, v in items:\nself[k] = v\nreturn self\ndef interpolate(self, use_variable: bool = True, interpolators: MutableMapping | None = None) -> FlatDict:\nr\"\"\"\n Perform Variable interpolation.\n Variable interpolation allows you to set the value of one key to be the value of another key easily.\n Args:\n use_variable: Whether to convert values to `Variable` objects.\n interpolators: Mapping contains values for interpolation. Defaults to `self`.\n Raises:\n ValueError: If value is not interpolatable.\n ValueError: If reference to itself.\n ValueError: If has circular reference.\n See Also:\n [Variable][`chanfig.Variable`]: Mutable wrapper of immutable objects.\n Examples:\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n >>> d.interpolate().dict()\n {'a': 1, 'b': 1, 'c': '1.1'}\n >>> isinstance(d.a, Variable)\n True\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 2, 'c': '1.1'}\n >>> d.a is d.b\n True\n >>> d.b is d.c\n False\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${b}'}\n >>> d.interpolate(False).dict()\n {'a': 1, 'b': 1, 'c': 1}\n >>> isinstance(d.a, Variable)\n False\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 1, 'c': 1}\n >>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Cannot interpolate b to itself.\n >>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Circular reference found: a->b->c->d->a.\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n ).\n \"\"\"\ninterpolators = interpolators or self\nplaceholders: dict[str, list[str]] = {}\nfor key, value in self.all_items():\nif isinstance(value, list):\nfor v in value:\nself.find_placeholders(key, v, placeholders)\nelif isinstance(value, Mapping):\nfor v in value.values():\nself.find_placeholders(key, v, placeholders)\nelse:\nself.find_placeholders(key, value, placeholders)\ncircular_references = find_circular_reference(placeholders)\nif circular_references:\nraise ValueError(f\"Circular reference found: {'->'.join(circular_references)}.\")\nif use_variable:\nplaceholder_names = {i for j in placeholders.values() for i in j}\nfor name in list(placeholder_names.difference(placeholders.keys())):\nif name not in interpolators:\nraise ValueError(f\"{name} is not found in {interpolators}.\")\nif not isinstance(interpolators[name], Variable):\ninterpolators[name] = Variable(interpolators[name])\nfor key, value in placeholders.items():\nif isinstance(self[key], list):\nfor index, v in enumerate(self[key]):\nself[key][index] = self.substitute(v, interpolators, value)\nelif isinstance(self[key], Mapping):\nfor k, v in self[key].items():\nself[key][k] = self.substitute(v, interpolators, value)\nelse:\nself[key] = self.substitute(self[key], interpolators, value)\nreturn self\n@staticmethod\ndef find_placeholders(key, value, placeholders):\nplaceholder = find_placeholders(value)\nif placeholder:\nfor index, name in enumerate(placeholder):\nif name.startswith(\".\"):\nplaceholder[index] = key.rsplit(\".\", 1)[0] + name\nif key == name:\nraise ValueError(f\"Cannot interpolate {key} to itself.\")\nplaceholders[key] = placeholder\n@staticmethod\ndef substitute(placeholder, interpolators, value):\ntry:\nif len(value) == 1 and placeholder.startswith(\"${\") and placeholder.endswith(\"}\"):\nreturn interpolators[value[0]]\nreturn placeholder.replace(\"$\", \"\").format(**interpolators)\nexcept KeyError as exc:\nraise ValueError(f\"{exc} is not found in {interpolators}.\") from None\ndef merge(self, *args: Any, overwrite: bool = True, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge `other` into `FlatDict`.\n Args:\n *args: `Mapping` or `Sequence` to be merged.\n overwrite: Whether to overwrite existing values.\n **kwargs: `Mapping` to be merged.\n Returns:\n self:\n **Alias**:\n + `union`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.merge(n).dict()\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.merge(l).dict()\n {'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n >>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d = FlatDict()\n >>> d.merge({1: 1, 2: 2, 3:3}).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge(d.clone()).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n {1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\n \"\"\"\nif len(args) == 1:\nargs = args[0]\nif isinstance(args, (PathLike, str, bytes)):\nargs = self.load(args) # type: ignore\nwarn(\n\"merge file is deprecated and maybe removed in a future release. Use `merge_from_file` instead.\",\nPendingDeprecationWarning,\n)\nself._merge(self, args, overwrite=overwrite)\nelif len(args) > 1:\nself._merge(self, args, overwrite=overwrite)\nif kwargs:\nself._merge(self, kwargs, overwrite=overwrite)\nreturn self\n@staticmethod\ndef _merge(this: FlatDict, that: Iterable, overwrite: bool = True) -> Mapping:\nif not that:\nreturn this\nif isinstance(that, Mapping):\nthat = that.items()\nfor key, value in that:\nif key in this and isinstance(this[key], Mapping):\nif isinstance(value, Mapping):\nFlatDict._merge(this[key], value)\nelif overwrite:\nif isinstance(value, FlatDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nelif overwrite or key not in this:\nthis.set(key, value)\nreturn this\ndef union(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`merge`][chanfig.FlatDict.merge].\n \"\"\"\nreturn self.merge(*args, **kwargs)\ndef merge_from_file(self, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge content of `file` into `FlatDict`.\n Args:\n file (File):\n *args: Passed to [`load`][chanfig.FlatDict.load].\n **kwargs: Passed to [`load`][chanfig.FlatDict.load].\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=1)\n >>> d.merge_from_file(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn self.merge(self.load(file, *args, **kwargs))\ndef intersect(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Intersection of `FlatDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n Returns:\n (FlatDict):\n **Alias**:\n + `inter`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.intersect(n).dict()\n {}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.intersect(l).dict()\n {'c': 3}\n >>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n {}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(**{key: value for key, value in other if key in self and self[key] == value}) # type: ignore\ndef inter(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`intersect`][chanfig.FlatDict.intersect].\n \"\"\"\nreturn self.intersect(other, *args, **kwargs)\ndef difference(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Difference between `FlatDict` and `other`.\n Args:\n other:\n Returns:\n (FlatDict):\n **Alias**:\n + `diff`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.difference(n).dict()\n {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.merge(l).difference(\"tests/test.yaml\").dict()\n {}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'b': 'b', 'c': 'c', 'd': 'd'}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(\n**{key: value for key, value in other if key not in self or self[key] != value} # type: ignore\n)\ndef diff(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`difference`][chanfig.FlatDict.difference].\n \"\"\"\nreturn self.difference(other, *args, **kwargs)\ndef to(self, cls: str | TorchDevice | TorchDType) -> FlatDict: # pragma: no cover\nr\"\"\"\n Convert values of `FlatDict` to target `cls`.\n Args:\n cls (str | torch.device | torch.dtype):\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.to(int)\n Traceback (most recent call last):\n TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\n \"\"\"\n# pylint: disable=C0103\nif isinstance(cls, (str, TorchDevice, TorchDType)):\nfor k, v in self.all_items():\nif hasattr(v, \"to\"):\nself[k] = v.to(cls)\nreturn self\nraise TypeError(f\"to() only support torch.dtype and torch.device, but got {cls}.\")\ndef cpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to cpu.\n Returns:\n self:\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.cpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cpu')}\n \"\"\"\nreturn self.to(TorchDevice(\"cpu\"))\ndef gpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to gpu.\n Returns:\n self:\n **Alias**:\n + `cuda`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.gpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n >>> d.cuda().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"cuda\"))\ndef cuda(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`gpu`][chanfig.FlatDict.gpu].\n \"\"\"\nreturn self.gpu()\ndef tpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to tpu.\n Returns:\n self:\n **Alias**:\n + `xla`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.tpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n >>> d.xla().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"xla\"))\ndef xla(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`tpu`][chanfig.FlatDict.tpu].\n \"\"\"\nreturn self.tpu()\ndef copy(self) -> FlatDict:\nr\"\"\"\n Create a shallow copy of `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.copy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': [1]}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nreturn copy(self)\ndef __deepcopy__(self, memo: Mapping | None = None) -> FlatDict:\n# pylint: disable=C0103\nif memo is not None and id(self) in memo:\nreturn memo[id(self)]\nret = self.empty()\nret.__dict__.update(deepcopy(self.__dict__))\nfor k, v in self.items():\nif isinstance(v, FlatDict):\nret[k] = v.deepcopy(memo=memo)\nelse:\nret[k] = deepcopy(v)\nreturn ret\ndef deepcopy(self, memo: Mapping | None = None) -> FlatDict: # pylint: disable=W0613\nr\"\"\"\n Create a deep copy of `FlatDict`.\n Returns:\n (FlatDict):\n **Alias**:\n + `clone`\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.deepcopy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': []}\n >>> c.getattr(\"name\")\n 'Chang'\n >>> d == d.clone() # alias\n True\n \"\"\"\nreturn deepcopy(self)\ndef clone(self, memo: Mapping | None = None) -> FlatDict:\nr\"\"\"\n Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].\n \"\"\"\nreturn self.deepcopy(memo=memo)\ndef save(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.save(\"tests/test.yaml\")\n >>> d.save(\"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... d.save(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nreturn self.yaml(file=file, *args, **kwargs) # type: ignore\nif extension in JSON:\nreturn self.json(file=file, *args, **kwargs) # type: ignore\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\ndef dump(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Alias of [`save`][chanfig.FlatDict.save].\n \"\"\"\nreturn self.save(file, method, *args, **kwargs)\n@classmethod\ndef load( # pylint: disable=W1113\ncls, file: File, method: str | None = None, *args: Any, **kwargs: Any\n) -> FlatDict:\n\"\"\"\n Load `FlatDict` from file.\n Args:\n file: File to load from.\n method: File type, should be in `JSON` or `YAML`.\n Returns:\n (FlatDict):\n Raises:\n ValueError: If load from `IO` and `method` is not specified.\n TypeError: If dump to unsupported extension.\n Examples:\n >>> d = FlatDict.load(\"tests/test.yaml\")\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.load(\"tests/test.conf\")\n Traceback (most recent call last):\n TypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"tests/test.yaml\") as f:\n ... d.load(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when loading from IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when loading from IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in JSON:\nreturn cls.from_json(file, *args, **kwargs)\nif extension in YAML:\nreturn cls.from_yaml(file, *args, **kwargs)\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\ndef json(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to json file.\n This method internally calls `self.jsons()` to generate json string.\n You may overwrite `jsons` in case something is not json serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.json(\"tests/test.json\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(self.jsons(*args, **kwargs))\n@classmethod\ndef from_json(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json file.\n This method internally calls `self.from_jsons()` to construct object from json string.\n You may overwrite `from_jsons` in case something is not json serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict.from_json('tests/test.json')\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_jsons(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_jsons(fp.read(), *args, **kwargs)\ndef jsons(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to json string.\n Returns:\n (str):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.jsons()\n '{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\n \"\"\"\nkwargs.setdefault(\"cls\", JsonEncoder)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn json_dumps(self.dict(), *args, **kwargs)\n@classmethod\ndef from_jsons(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nreturn cls.from_dict(json_loads(string, *args, **kwargs))\ndef yaml(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to yaml file.\n This method internally calls `self.yamls()` to generate yaml string.\n You may overwrite `yamls` in case something is not yaml serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.yaml(\"tests/test.yaml\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nself.yamls(fp, *args, **kwargs)\n@classmethod\ndef from_yaml(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml file.\n This method internally calls `self.from_yamls()` to construct object from yaml string.\n You may overwrite `from_yamls` in case something is not yaml serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yaml('tests/test.yaml').dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nkwargs.setdefault(\"Loader\", YamlLoader)\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_yamls(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_dict(yaml_load(fp, *args, **kwargs))\ndef yamls(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to yaml string.\n Returns:\n (str):\n Examples:\n >>> FlatDict(a=1, b=2, c=3).yamls()\n 'a: 1\\nb: 2\\nc: 3\\n'\n \"\"\"\nkwargs.setdefault(\"Dumper\", YamlDumper)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn yaml_dump(self.dict(), *args, **kwargs) # type: ignore\n@classmethod\ndef from_yamls(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nkwargs.setdefault(\"Loader\", SafeLoader)\nreturn cls.from_dict(yaml_load(string, *args, **kwargs))\n@staticmethod\n@contextmanager\ndef open(file: File, *args: Any, encoding: str = \"utf-8\", **kwargs: Any) -> Generator[IOBase | IO, Any, Any]:\nr\"\"\"\n Open file IO from file path or IO.\n This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.\n Args:\n file: File path or IO.\n *args: Additional arguments passed to `open`.\n Defaults to ().\n **kwargs: Any\n Additional keyword arguments passed to `open`.\n Defaults to {}.\n Yields:\n (Generator[IOBase | IO, Any, Any]):\n Examples:\n >>> with FlatDict.open(\"tests/test.yaml\") as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> io = open(\"tests/test.yaml\")\n >>> with FlatDict.open(io) as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> with FlatDict.open(123, mode=\"w\") as fp:\n ... print(fp.read())\n Traceback (most recent call last):\n TypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\n \"\"\"\nif isinstance(file, (IOBase, IO)):\nyield file\nelif isinstance(file, (PathLike, str, bytes)):\ntry:\nfile = open(file, *args, encoding=encoding, **kwargs) # type: ignore # noqa: SIM115\nyield file # type: ignore\nfinally:\nwith suppress(Exception):\nfile.close() # type: ignore\nelse:\nraise TypeError(f\"expected str, bytes, os.PathLike, IO or IOBase, not {type(file).__name__}\")\n@classmethod\ndef empty(cls, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty `FlatDict`.\n This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.\n As use `type(self)()` in this case would copy all the default values, which might not be desired.\n This method will preserve everything in `FlatDict.__class__.__dict__`.\n Returns:\n (FlatDict):\n See Also:\n [`empty_like`][chanfig.FlatDict.empty_like]\n Examples:\n >>> d = FlatDict(a=[])\n >>> c = d.empty()\n >>> c.dict()\n {}\n \"\"\"\nempty = cls.__new__(cls)\nempty.merge(*args, **kwargs) # pylint: disable=W0212\nreturn empty\ndef empty_like(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty copy of `FlatDict`.\n This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.\n For example, `property`s are saved in `__dict__`, they will keep their original reference after calling this\n method.\n Returns:\n (FlatDict):\n See Also:\n [`empty`][chanfig.FlatDict.empty]\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.empty_like()\n >>> c.dict()\n {}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nempty = self.empty(*args, **kwargs)\nempty.__dict__.update(self.__dict__)\nreturn empty\ndef all_keys(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_keys`][chanfig.NestedDict.all_keys]\n \"\"\"\nyield from self.keys()\ndef all_values(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_values`][chanfig.NestedDict.all_values]\n \"\"\"\nyield from self.values()\ndef all_items(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_items`][chanfig.NestedDict.all_items]\n \"\"\"\nyield from self.items()\ndef dropnull(self) -> FlatDict:\nr\"\"\"\n Drop key-value pairs with `Null` value.\n Returns:\n (FlatDict):\n **Alias**:\n + `dropna`\n Examples:\n >>> d = FlatDict(a=Null, b=Null, c=3)\n >>> d.dict()\n {'a': Null, 'b': Null, 'c': 3}\n >>> d.dropnull().dict()\n {'c': 3}\n >>> d.dropna().dict() # alias\n {'c': 3}\n \"\"\"\nreturn self.empty({k: v for k, v in self.all_items() if v is not Null})\ndef dropna(self) -> FlatDict:\nr\"\"\"\n Alias of [`dropnull`][chanfig.FlatDict.dropnull].\n \"\"\"\nreturn self.dropnull()\n@staticmethod\ndef extra_repr() -> str: # pylint: disable=C0116\nreturn \"\"\ndef __repr__(self) -> str:\nextra_lines = []\nextra_repr = self.extra_repr()\n# empty string will be split into list ['']\nif extra_repr:\nextra_lines = extra_repr.split(\"\\n\")\nchild_lines = []\nfor key, value in self.items():\nkey_repr = repr(key)\nvalue_repr = repr(value)\nvalue_repr = self._add_indent(value_repr)\nchild_lines.append(f\"({key_repr}): {value_repr}\")\n# child_lines.append(f\"{key_repr}: {value_repr}\")\nlines = extra_lines + child_lines\nmain_repr = self.__class__.__name__ + \"(\"\nif lines:\n# simple one-liner info, which most builtin Modules will use\nif len(extra_lines) == 1 and not child_lines:\nmain_repr += extra_lines[0]\nelif len(child_lines) == 1 and not extra_lines and len(child_lines[0]) < 10:\nmain_repr += child_lines[0]\nelse:\nmain_repr += \"\\n \" + \"\\n \".join(lines) + \"\\n\"\nmain_repr += \")\"\nreturn main_repr\ndef _add_indent(self, text: str) -> str:\nlines = text.split(\"\\n\")\n# don't do anything for single-line stuff\nif len(lines) == 1:\nreturn text\nfirst = lines.pop(0)\nlines = [(self.getattr(\"indent\", 2) * \" \") + line for line in lines]\ntext = \"\\n\".join(lines)\ntext = first + \"\\n\" + text\nreturn text\ndef __format__(self, format_spec: str) -> str:\nreturn repr(self.empty({k: v.__format__(format_spec) for k, v in self.all_items()}))\ndef __hash__(self):\nreturn hash(frozenset(self.items()))\ndef _ipython_display_(self): # pragma: no cover\nreturn repr(self)\ndef _ipython_canary_method_should_not_exist_(self): # pragma: no cover\nreturn None\ndef aihwerij235234ljsdnp34ksodfipwoe234234jlskjdf(self): # pragma: no cover\nreturn None\ndef __rich__(self): # pragma: no cover\nreturn self.__repr__()\nall_items()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_items
chanfig/flat_dict.py Pythondef all_items(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_items`][chanfig.NestedDict.all_items]\n \"\"\"\nyield from self.items()\nall_keys()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_keys
chanfig/flat_dict.py Pythondef all_keys(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_keys`][chanfig.NestedDict.all_keys]\n \"\"\"\nyield from self.keys()\nall_values()","text":"Equivalent to keys.
This method is provided solely to make methods work on both FlatDict and NestedDict.
all_values
chanfig/flat_dict.py Pythondef all_values(self) -> Generator:\nr\"\"\"\n Equivalent to `keys`.\n This method is provided solely to make methods work on both `FlatDict` and `NestedDict`.\n See Also:\n [`all_values`][chanfig.NestedDict.all_values]\n \"\"\"\nyield from self.values()\nclone(memo=None)","text":"Alias of deepcopy.
chanfig/flat_dict.py Pythondef clone(self, memo: Mapping | None = None) -> FlatDict:\nr\"\"\"\n Alias of [`deepcopy`][chanfig.FlatDict.deepcopy].\n \"\"\"\nreturn self.deepcopy(memo=memo)\ncopy()","text":"Create a shallow copy of FlatDict.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.copy()\n>>> c.dict()\n{'a': []}\n>>> d.a.append(1)\n>>> c.dict()\n{'a': [1]}\n>>> c.getattr(\"name\")\n'Chang'\nchanfig/flat_dict.py Pythondef copy(self) -> FlatDict:\nr\"\"\"\n Create a shallow copy of `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.copy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': [1]}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nreturn copy(self)\ncpu()","text":"Move all tensors to cpu.
Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.cpu().dict()\n{'a': tensor(1, device='cpu')}\nchanfig/flat_dict.py Pythondef cpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to cpu.\n Returns:\n self:\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.cpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cpu')}\n \"\"\"\nreturn self.to(TorchDevice(\"cpu\"))\ncuda()","text":"Alias of gpu.
chanfig/flat_dict.py Pythondef cuda(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`gpu`][chanfig.FlatDict.gpu].\n \"\"\"\nreturn self.gpu()\ndeepcopy(memo=None)","text":"Create a deep copy of FlatDict.
Returns:
Type DescriptionFlatDict Alias:
cloneExamples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.deepcopy()\n>>> c.dict()\n{'a': []}\n>>> d.a.append(1)\n>>> c.dict()\n{'a': []}\n>>> c.getattr(\"name\")\n'Chang'\n>>> d == d.clone() # alias\nTrue\nchanfig/flat_dict.py Pythondef deepcopy(self, memo: Mapping | None = None) -> FlatDict: # pylint: disable=W0613\nr\"\"\"\n Create a deep copy of `FlatDict`.\n Returns:\n (FlatDict):\n **Alias**:\n + `clone`\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.deepcopy()\n >>> c.dict()\n {'a': []}\n >>> d.a.append(1)\n >>> c.dict()\n {'a': []}\n >>> c.getattr(\"name\")\n 'Chang'\n >>> d == d.clone() # alias\n True\n \"\"\"\nreturn deepcopy(self)\ndelattr(name)","text":"Delete attribute of FlatDict.
Note that it won\u2019t delete values in FlatDict.
Parameters:
Name Type Description Defaultname str required Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('name', 'chang')\n>>> d.getattr('name')\n'chang'\n>>> d.delattr('name')\n>>> d.getattr('name')\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'name'\nchanfig/flat_dict.py Pythondef delattr(self, name: str) -> None:\nr\"\"\"\n Delete attribute of `FlatDict`.\n Note that it won't delete values in `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.getattr('name')\n 'chang'\n >>> d.delattr('name')\n >>> d.getattr('name')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'name'\n \"\"\"\ndel self.__dict__[name]\ndelete(name)","text":"Delete value from FlatDict.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = FlatDict(d=1016, n='chang')\n>>> d.d\n1016\n>>> d.n\n'chang'\n>>> d.delete('d')\n>>> d.d\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'd'\n>>> del d.n\n>>> d.n\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'n'\n>>> del d.f\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'f'\nchanfig/flat_dict.py Pythondef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `FlatDict`.\n Args:\n name:\n Examples:\n >>> d = FlatDict(d=1016, n='chang')\n >>> d.d\n 1016\n >>> d.n\n 'chang'\n >>> d.delete('d')\n >>> d.d\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'd'\n >>> del d.n\n >>> d.n\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'n'\n >>> del d.f\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'f'\n \"\"\"\ndict.__delitem__(self, name)\ndict(cls=dict)","text":"Convert FlatDict to other Mapping.
Parameters:
Name Type Description Defaultcls Callable Target class to be converted to.
dict Returns:
Type DescriptionMapping See Also to_dict: Implementation of dict.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Pythondef dict(self, cls: Callable = dict) -> Mapping:\nr\"\"\"\n Convert `FlatDict` to other `Mapping`.\n Args:\n cls: Target class to be converted to.\n Returns:\n (Mapping):\n See Also:\n [`to_dict`][chanfig.flat_dict.to_dict]: Implementation of `dict`.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn cls(to_dict(self))\ndiff(other, *args, **kwargs)","text":"Alias of difference.
chanfig/flat_dict.py Pythondef diff(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`difference`][chanfig.FlatDict.difference].\n \"\"\"\nreturn self.difference(other, *args, **kwargs)\ndifference(other)","text":"Difference between FlatDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required Returns:
Type DescriptionFlatDict Alias:
diffExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.difference(n).dict()\n{'b': 'b', 'c': 'c', 'd': 'd'}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.difference(l).dict()\n{'d': 4}\n>>> d.merge(l).difference(\"tests/test.yaml\").dict()\n{}\n>>> d.difference(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n>>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n{'b': 'b', 'c': 'c', 'd': 'd'}\nchanfig/flat_dict.py Pythondef difference(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Difference between `FlatDict` and `other`.\n Args:\n other:\n Returns:\n (FlatDict):\n **Alias**:\n + `diff`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.difference(n).dict()\n {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.merge(l).difference(\"tests/test.yaml\").dict()\n {}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> FlatDict(a=1, b=1, c=1).diff(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'b': 'b', 'c': 'c', 'd': 'd'}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(\n**{key: value for key, value in other if key not in self or self[key] != value} # type: ignore\n)\ndropna()","text":"Alias of dropnull.
chanfig/flat_dict.py Pythondef dropna(self) -> FlatDict:\nr\"\"\"\n Alias of [`dropnull`][chanfig.FlatDict.dropnull].\n \"\"\"\nreturn self.dropnull()\ndropnull()","text":"Drop key-value pairs with Null value.
Returns:
Type DescriptionFlatDict Alias:
dropnaExamples:
Python Console Session>>> d = FlatDict(a=Null, b=Null, c=3)\n>>> d.dict()\n{'a': Null, 'b': Null, 'c': 3}\n>>> d.dropnull().dict()\n{'c': 3}\n>>> d.dropna().dict() # alias\n{'c': 3}\nchanfig/flat_dict.py Pythondef dropnull(self) -> FlatDict:\nr\"\"\"\n Drop key-value pairs with `Null` value.\n Returns:\n (FlatDict):\n **Alias**:\n + `dropna`\n Examples:\n >>> d = FlatDict(a=Null, b=Null, c=3)\n >>> d.dict()\n {'a': Null, 'b': Null, 'c': 3}\n >>> d.dropnull().dict()\n {'c': 3}\n >>> d.dropna().dict() # alias\n {'c': 3}\n \"\"\"\nreturn self.empty({k: v for k, v in self.all_items() if v is not Null})\ndump(file, method=None, *args, **kwargs)","text":"Alias of save.
chanfig/flat_dict.py Pythondef dump(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Alias of [`save`][chanfig.FlatDict.save].\n \"\"\"\nreturn self.save(file, method, *args, **kwargs)\nempty(*args, **kwargs) classmethod","text":"Initialise an empty FlatDict.
This method is helpful when you inheriting FlatDict with default values defined in __init__(). As use type(self)() in this case would copy all the default values, which might not be desired.
This method will preserve everything in FlatDict.__class__.__dict__.
Returns:
Type DescriptionFlatDict See Also empty_like
Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> c = d.empty()\n>>> c.dict()\n{}\nchanfig/flat_dict.py Python@classmethod\ndef empty(cls, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty `FlatDict`.\n This method is helpful when you inheriting `FlatDict` with default values defined in `__init__()`.\n As use `type(self)()` in this case would copy all the default values, which might not be desired.\n This method will preserve everything in `FlatDict.__class__.__dict__`.\n Returns:\n (FlatDict):\n See Also:\n [`empty_like`][chanfig.FlatDict.empty_like]\n Examples:\n >>> d = FlatDict(a=[])\n >>> c = d.empty()\n >>> c.dict()\n {}\n \"\"\"\nempty = cls.__new__(cls)\nempty.merge(*args, **kwargs) # pylint: disable=W0212\nreturn empty\nempty_like(*args, **kwargs)","text":"Initialise an empty copy of FlatDict.
This method will preserve everything in FlatDict.__class__.__dict__ and FlatDict.__dict__.
For example, propertys are saved in __dict__, they will keep their original reference after calling this method.
Returns:
Type DescriptionFlatDict See Also empty
Examples:
Python Console Session>>> d = FlatDict(a=[])\n>>> d.setattr(\"name\", \"Chang\")\n>>> c = d.empty_like()\n>>> c.dict()\n{}\n>>> c.getattr(\"name\")\n'Chang'\nchanfig/flat_dict.py Pythondef empty_like(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Initialise an empty copy of `FlatDict`.\n This method will preserve everything in `FlatDict.__class__.__dict__` and `FlatDict.__dict__`.\n For example, `property`s are saved in `__dict__`, they will keep their original reference after calling this\n method.\n Returns:\n (FlatDict):\n See Also:\n [`empty`][chanfig.FlatDict.empty]\n Examples:\n >>> d = FlatDict(a=[])\n >>> d.setattr(\"name\", \"Chang\")\n >>> c = d.empty_like()\n >>> c.dict()\n {}\n >>> c.getattr(\"name\")\n 'Chang'\n \"\"\"\nempty = self.empty(*args, **kwargs)\nempty.__dict__.update(self.__dict__)\nreturn empty\nfrom_dict(obj) classmethod","text":"Convert Mapping or Sequence to FlatDict.
Examples:
Python Console Session>>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\nFlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\n>>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\nFlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\n>>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n>>> FlatDict.from_dict({1, 2, 3})\nTraceback (most recent call last):\nTypeError: Expected Mapping or Sequence, but got <class 'set'>.\nchanfig/flat_dict.py Python@classmethod\ndef from_dict(cls, obj: Mapping | Sequence) -> Any: # pylint: disable=R0911\nr\"\"\"\n Convert `Mapping` or `Sequence` to `FlatDict`.\n Examples:\n >>> FlatDict.from_dict({'a': 1, 'b': 2, 'c': 3})\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([('a', 1), ('b', 2), ('c', 3)])\n FlatDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n >>> FlatDict.from_dict([{'a': 1}, {'b': 2}, {'c': 3}])\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n >>> FlatDict.from_dict({1, 2, 3})\n Traceback (most recent call last):\n TypeError: Expected Mapping or Sequence, but got <class 'set'>.\n \"\"\"\nif obj is None:\nreturn cls()\nif issubclass(cls, FlatDict):\ncls = cls.empty # type: ignore # pylint: disable=W0642\nif isinstance(obj, Mapping):\nreturn cls(obj)\nif isinstance(obj, Sequence):\ntry:\nreturn cls(obj)\nexcept ValueError:\nreturn [cls(json) for json in obj]\nraise TypeError(f\"Expected Mapping or Sequence, but got {type(obj)}.\")\nfrom_json(file, *args, **kwargs) classmethod","text":"Construct FlatDict from json file.
This method internally calls self.from_jsons() to construct object from json string. You may overwrite from_jsons in case something is not json serializable.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict.from_json('tests/test.json')\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Python@classmethod\ndef from_json(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json file.\n This method internally calls `self.from_jsons()` to construct object from json string.\n You may overwrite `from_jsons` in case something is not json serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict.from_json('tests/test.json')\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_jsons(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_jsons(fp.read(), *args, **kwargs)\nfrom_jsons(string, *args, **kwargs) classmethod","text":"Construct FlatDict from json string.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\nchanfig/flat_dict.py Python@classmethod\ndef from_jsons(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from json string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_jsons('{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[[\"a\", 1], [\"b\", 2], [\"c\", 3]]').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_jsons('[{\"a\": 1}, {\"b\": 2}, {\"c\": 3}]')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nreturn cls.from_dict(json_loads(string, *args, **kwargs))\nfrom_yaml(file, *args, **kwargs) classmethod","text":"Construct FlatDict from yaml file.
This method internally calls self.from_yamls() to construct object from yaml string. You may overwrite from_yamls in case something is not yaml serializable.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_yaml('tests/test.yaml').dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Python@classmethod\ndef from_yaml(cls, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml file.\n This method internally calls `self.from_yamls()` to construct object from yaml string.\n You may overwrite `from_yamls` in case something is not yaml serializable.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yaml('tests/test.yaml').dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nkwargs.setdefault(\"Loader\", YamlLoader)\nwith cls.open(file) as fp: # pylint: disable=C0103\nif isinstance(file, (IOBase, IO)):\nreturn cls.from_yamls(fp.getvalue(), *args, **kwargs) # type: ignore\nreturn cls.from_dict(yaml_load(fp, *args, **kwargs))\nfrom_yamls(string, *args, **kwargs) classmethod","text":"Construct FlatDict from yaml string.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n[FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\nchanfig/flat_dict.py Python@classmethod\ndef from_yamls(cls, string: str, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Construct `FlatDict` from yaml string.\n Returns:\n (FlatDict):\n Examples:\n >>> FlatDict.from_yamls('a: 1\\nb: 2\\nc: 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- - a\\n - 1\\n- - b\\n - 2\\n- - c\\n - 3\\n').dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> FlatDict.from_yamls('- a: 1\\n- b: 2\\n- c: 3\\n')\n [FlatDict(('a'): 1), FlatDict(('b'): 2), FlatDict(('c'): 3)]\n \"\"\"\nkwargs.setdefault(\"Loader\", SafeLoader)\nreturn cls.from_dict(yaml_load(string, *args, **kwargs))\nget(name, default=None)","text":"Get value from FlatDict.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If FlatDict does not contain name, return default.
Raises:
Type DescriptionKeyError If FlatDict does not contain name and default is not specified.
TypeError If name is not hashable.
Examples:
Python Console Session>>> d = FlatDict(d=1013)\n>>> d.get('d')\n1013\n>>> d['d']\n1013\n>>> d.d\n1013\n>>> d.get('d', None)\n1013\n>>> d.get('f', 2)\n2\n>>> d.get('f')\n>>> d.get('f', Null)\nTraceback (most recent call last):\nKeyError: 'f'\nchanfig/flat_dict.py Pythondef get(self, name: Any, default: Any = None) -> Any:\nr\"\"\"\n Get value from `FlatDict`.\n Args:\n name:\n default:\n Returns:\n value:\n If `FlatDict` does not contain `name`, return `default`.\n Raises:\n KeyError: If `FlatDict` does not contain `name` and `default` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = FlatDict(d=1013)\n >>> d.get('d')\n 1013\n >>> d['d']\n 1013\n >>> d.d\n 1013\n >>> d.get('d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('f')\n >>> d.get('f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\nif name in self:\nreturn dict.__getitem__(self, name)\nif default is not Null:\nreturn default\nreturn self.__missing__(name)\ngetattr(name, default=Null)","text":"Get attribute of FlatDict.
Note that it won\u2019t retrieve value in FlatDict,
Parameters:
Name Type Description Defaultname str required default Any Null Returns:
Name Type Descriptionvalue Any If FlatDict does not contain name, return default.
Raises:
Type DescriptionAttributeError If FlatDict does not contain name and default is not specified.
Examples:
Python Console Session>>> d = FlatDict(a=1)\n>>> d.get('a')\n1\n>>> d.getattr('a')\nTraceback (most recent call last):\nAttributeError: 'FlatDict' object has no attribute 'a'\n>>> d.getattr('b', 2)\n2\n>>> d.setattr('b', 3)\n>>> d.getattr('b')\n3\nchanfig/flat_dict.py Pythondef getattr(self, name: str, default: Any = Null) -> Any:\nr\"\"\"\n Get attribute of `FlatDict`.\n Note that it won't retrieve value in `FlatDict`,\n Args:\n name:\n default:\n Returns:\n value: If `FlatDict` does not contain `name`, return `default`.\n Raises:\n AttributeError: If `FlatDict` does not contain `name` and `default` is not specified.\n Examples:\n >>> d = FlatDict(a=1)\n >>> d.get('a')\n 1\n >>> d.getattr('a')\n Traceback (most recent call last):\n AttributeError: 'FlatDict' object has no attribute 'a'\n >>> d.getattr('b', 2)\n 2\n >>> d.setattr('b', 3)\n >>> d.getattr('b')\n 3\n \"\"\"\ntry:\nif name in self.__dict__:\nreturn self.__dict__[name]\nif name in self.__class__.__dict__:\nreturn self.__class__.__dict__[name]\nreturn super().getattr(name, default) # type: ignore\nexcept AttributeError:\nif default is not Null:\nreturn default\nraise AttributeError(f\"'{self.__class__.__name__}' object has no attribute '{name}'\") from None\ngpu()","text":"Move all tensors to gpu.
Returns:
Name Type Descriptionself FlatDict Alias:
cudaExamples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.gpu().dict()\n{'a': tensor(1, device='cuda:0')}\n>>> d.cuda().dict() # alias\n{'a': tensor(1, device='cuda:0')}\nchanfig/flat_dict.py Pythondef gpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to gpu.\n Returns:\n self:\n **Alias**:\n + `cuda`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.gpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n >>> d.cuda().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='cuda:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"cuda\"))\nhasattr(name)","text":"Determine if an attribute exists in FlatDict.
Parameters:
Name Type Description Defaultname str required Returns:
Type Descriptionbool Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('name', 'chang')\n>>> d.hasattr('name')\nTrue\n>>> d.delattr('name')\n>>> d.hasattr('name')\nFalse\nchanfig/flat_dict.py Pythondef hasattr(self, name: str) -> bool:\nr\"\"\"\n Determine if an attribute exists in `FlatDict`.\n Args:\n name:\n Returns:\n (bool):\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('name', 'chang')\n >>> d.hasattr('name')\n True\n >>> d.delattr('name')\n >>> d.hasattr('name')\n False\n \"\"\"\ntry:\nif name in self.__dict__ or name in self.__class__.__dict__:\nreturn True\nreturn super().hasattr(name) # type: ignore\nexcept AttributeError:\nreturn False\ninter(other, *args, **kwargs)","text":"Alias of intersect.
chanfig/flat_dict.py Pythondef inter(self, other: Mapping | Iterable | PathStr, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`intersect`][chanfig.FlatDict.intersect].\n \"\"\"\nreturn self.intersect(other, *args, **kwargs)\ninterpolate(use_variable=True, interpolators=None)","text":"Perform Variable interpolation.
Variable interpolation allows you to set the value of one key to be the value of another key easily.
Parameters:
Name Type Description Defaultuse_variable bool Whether to convert values to Variable objects.
True interpolators MutableMapping | None Mapping contains values for interpolation. Defaults to self.
None Raises:
Type DescriptionValueError If value is not interpolatable.
ValueError If reference to itself.
ValueError If has circular reference.
See Also[Variable][chanfig.Variable]: Mutable wrapper of immutable objects.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n>>> d.dict()\n{'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n>>> d.interpolate().dict()\n{'a': 1, 'b': 1, 'c': '1.1'}\n>>> isinstance(d.a, Variable)\nTrue\n>>> d.a += 1\n>>> d.dict()\n{'a': 2, 'b': 2, 'c': '1.1'}\n>>> d.a is d.b\nTrue\n>>> d.b is d.c\nFalse\n>>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n>>> d.dict()\n{'a': 1, 'b': '${a}', 'c': '${b}'}\n>>> d.interpolate(False).dict()\n{'a': 1, 'b': 1, 'c': 1}\n>>> isinstance(d.a, Variable)\nFalse\n>>> d.a += 1\n>>> d.dict()\n{'a': 2, 'b': 1, 'c': 1}\n>>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: Cannot interpolate b to itself.\n>>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: Circular reference found: a->b->c->d->a.\n>>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n>>> d.interpolate().dict()\nTraceback (most recent call last):\nValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n).\nchanfig/flat_dict.py Pythondef interpolate(self, use_variable: bool = True, interpolators: MutableMapping | None = None) -> FlatDict:\nr\"\"\"\n Perform Variable interpolation.\n Variable interpolation allows you to set the value of one key to be the value of another key easily.\n Args:\n use_variable: Whether to convert values to `Variable` objects.\n interpolators: Mapping contains values for interpolation. Defaults to `self`.\n Raises:\n ValueError: If value is not interpolatable.\n ValueError: If reference to itself.\n ValueError: If has circular reference.\n See Also:\n [Variable][`chanfig.Variable`]: Mutable wrapper of immutable objects.\n Examples:\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${a}.${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${a}.${b}'}\n >>> d.interpolate().dict()\n {'a': 1, 'b': 1, 'c': '1.1'}\n >>> isinstance(d.a, Variable)\n True\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 2, 'c': '1.1'}\n >>> d.a is d.b\n True\n >>> d.b is d.c\n False\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${b}\")\n >>> d.dict()\n {'a': 1, 'b': '${a}', 'c': '${b}'}\n >>> d.interpolate(False).dict()\n {'a': 1, 'b': 1, 'c': 1}\n >>> isinstance(d.a, Variable)\n False\n >>> d.a += 1\n >>> d.dict()\n {'a': 2, 'b': 1, 'c': 1}\n >>> d = FlatDict(a=1, b=\"${b}\", c=\"${b}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Cannot interpolate b to itself.\n >>> d = FlatDict(a=\"${b}\", b=\"${c}\", c=\"${d}\", d=\"${a}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: Circular reference found: a->b->c->d->a.\n >>> d = FlatDict(a=1, b=\"${a}\", c=\"${d}\")\n >>> d.interpolate().dict()\n Traceback (most recent call last):\n ValueError: d is not found in FlatDict(\n ('a'): '1'\n ('b'): '${a}'\n ('c'): '${d}'\n ).\n \"\"\"\ninterpolators = interpolators or self\nplaceholders: dict[str, list[str]] = {}\nfor key, value in self.all_items():\nif isinstance(value, list):\nfor v in value:\nself.find_placeholders(key, v, placeholders)\nelif isinstance(value, Mapping):\nfor v in value.values():\nself.find_placeholders(key, v, placeholders)\nelse:\nself.find_placeholders(key, value, placeholders)\ncircular_references = find_circular_reference(placeholders)\nif circular_references:\nraise ValueError(f\"Circular reference found: {'->'.join(circular_references)}.\")\nif use_variable:\nplaceholder_names = {i for j in placeholders.values() for i in j}\nfor name in list(placeholder_names.difference(placeholders.keys())):\nif name not in interpolators:\nraise ValueError(f\"{name} is not found in {interpolators}.\")\nif not isinstance(interpolators[name], Variable):\ninterpolators[name] = Variable(interpolators[name])\nfor key, value in placeholders.items():\nif isinstance(self[key], list):\nfor index, v in enumerate(self[key]):\nself[key][index] = self.substitute(v, interpolators, value)\nelif isinstance(self[key], Mapping):\nfor k, v in self[key].items():\nself[key][k] = self.substitute(v, interpolators, value)\nelse:\nself[key] = self.substitute(self[key], interpolators, value)\nreturn self\nintersect(other)","text":"Intersection of FlatDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required Returns:
Type DescriptionFlatDict Alias:
interExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.intersect(n).dict()\n{}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.intersect(l).dict()\n{'c': 3}\n>>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d.intersect(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n>>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n{}\nchanfig/flat_dict.py Pythondef intersect(self, other: Mapping | Iterable | PathStr) -> FlatDict:\nr\"\"\"\n Intersection of `FlatDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n Returns:\n (FlatDict):\n **Alias**:\n + `inter`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.intersect(n).dict()\n {}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.intersect(l).dict()\n {'c': 3}\n >>> d.merge(l).intersect(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n >>> d.inter(FlatDict(b='b', c='c', d='d')).dict() # alias\n {}\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(**{key: value for key, value in other if key in self and self[key] == value}) # type: ignore\njson(file, *args, **kwargs)","text":"Dump FlatDict to json file.
This method internally calls self.jsons() to generate json string. You may overwrite jsons in case something is not json serializable.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.json(\"tests/test.json\")\nchanfig/flat_dict.py Pythondef json(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to json file.\n This method internally calls `self.jsons()` to generate json string.\n You may overwrite `jsons` in case something is not json serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.json(\"tests/test.json\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(self.jsons(*args, **kwargs))\njsons(*args, **kwargs)","text":"Dump FlatDict to json string.
Returns:
Type Descriptionstr Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.jsons()\n'{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\nchanfig/flat_dict.py Pythondef jsons(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to json string.\n Returns:\n (str):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.jsons()\n '{\\n \"a\": 1,\\n \"b\": 2,\\n \"c\": 3\\n}'\n \"\"\"\nkwargs.setdefault(\"cls\", JsonEncoder)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn json_dumps(self.dict(), *args, **kwargs)\nload(file, method=None, *args, **kwargs) classmethod","text":"Load FlatDict from file.
Parameters:
Name Type Description Defaultfile File File to load from.
requiredmethod str | None File type, should be in JSON or YAML.
None Returns:
Type DescriptionFlatDict Raises:
Type DescriptionValueError If load from IO and method is not specified.
TypeError If dump to unsupported extension.
Examples:
Python Console Session>>> d = FlatDict.load(\"tests/test.yaml\")\n>>> d.dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d.load(\"tests/test.conf\")\nTraceback (most recent call last):\nTypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"tests/test.yaml\") as f:\n... d.load(f)\nTraceback (most recent call last):\nValueError: `method` must be specified when loading from IO.\nchanfig/flat_dict.py Python@classmethod\ndef load( # pylint: disable=W1113\ncls, file: File, method: str | None = None, *args: Any, **kwargs: Any\n) -> FlatDict:\n\"\"\"\n Load `FlatDict` from file.\n Args:\n file: File to load from.\n method: File type, should be in `JSON` or `YAML`.\n Returns:\n (FlatDict):\n Raises:\n ValueError: If load from `IO` and `method` is not specified.\n TypeError: If dump to unsupported extension.\n Examples:\n >>> d = FlatDict.load(\"tests/test.yaml\")\n >>> d.dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d.load(\"tests/test.conf\")\n Traceback (most recent call last):\n TypeError: `file='tests/test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"tests/test.yaml\") as f:\n ... d.load(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when loading from IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when loading from IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in JSON:\nreturn cls.from_json(file, *args, **kwargs)\nif extension in YAML:\nreturn cls.from_yaml(file, *args, **kwargs)\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\nmerge(*args, overwrite=True, **kwargs)","text":"Merge other into FlatDict.
Parameters:
Name Type Description Default*args Any Mapping or Sequence to be merged.
() overwrite bool Whether to overwrite existing values.
True **kwargs Any Mapping to be merged.
{} Returns:
Name Type Descriptionself FlatDict Alias:
unionExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d.merge(n).dict()\n{'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n>>> l = [('c', 3), ('d', 4)]\n>>> d.merge(l).dict()\n{'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n>>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n{'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n>>> d = FlatDict()\n>>> d.merge({1: 1, 2: 2, 3:3}).dict()\n{1: 1, 2: 2, 3: 3}\n>>> d.merge(d.clone()).dict()\n{1: 1, 2: 2, 3: 3}\n>>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n{1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\nchanfig/flat_dict.py Pythondef merge(self, *args: Any, overwrite: bool = True, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge `other` into `FlatDict`.\n Args:\n *args: `Mapping` or `Sequence` to be merged.\n overwrite: Whether to overwrite existing values.\n **kwargs: `Mapping` to be merged.\n Returns:\n self:\n **Alias**:\n + `union`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> n = {'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d.merge(n).dict()\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> l = [('c', 3), ('d', 4)]\n >>> d.merge(l).dict()\n {'a': 1, 'b': 'b', 'c': 3, 'd': 4}\n >>> FlatDict(a=1, b=1, c=1).union(FlatDict(b='b', c='c', d='d')).dict() # alias\n {'a': 1, 'b': 'b', 'c': 'c', 'd': 'd'}\n >>> d = FlatDict()\n >>> d.merge({1: 1, 2: 2, 3:3}).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge(d.clone()).dict()\n {1: 1, 2: 2, 3: 3}\n >>> d.merge({1:3, 2:1, 3: 2, 4: 4, 5: 5}, overwrite=False).dict()\n {1: 1, 2: 2, 3: 3, 4: 4, 5: 5}\n \"\"\"\nif len(args) == 1:\nargs = args[0]\nif isinstance(args, (PathLike, str, bytes)):\nargs = self.load(args) # type: ignore\nwarn(\n\"merge file is deprecated and maybe removed in a future release. Use `merge_from_file` instead.\",\nPendingDeprecationWarning,\n)\nself._merge(self, args, overwrite=overwrite)\nelif len(args) > 1:\nself._merge(self, args, overwrite=overwrite)\nif kwargs:\nself._merge(self, kwargs, overwrite=overwrite)\nreturn self\nmerge_from_file(file, *args, **kwargs)","text":"Merge content of file into FlatDict.
Parameters:
Name Type Description Defaultfile File required *args Any Passed to load.
() **kwargs Any Passed to load.
{} Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=1)\n>>> d.merge_from_file(\"tests/test.yaml\").dict()\n{'a': 1, 'b': 2, 'c': 3}\nchanfig/flat_dict.py Pythondef merge_from_file(self, file: File, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Merge content of `file` into `FlatDict`.\n Args:\n file (File):\n *args: Passed to [`load`][chanfig.FlatDict.load].\n **kwargs: Passed to [`load`][chanfig.FlatDict.load].\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=1)\n >>> d.merge_from_file(\"tests/test.yaml\").dict()\n {'a': 1, 'b': 2, 'c': 3}\n \"\"\"\nreturn self.merge(self.load(file, *args, **kwargs))\nopen(file, *args, encoding='utf-8', **kwargs) staticmethod","text":"Open file IO from file path or IO.
This methods extends the ability of built-in open by allowing it to accept an IOBase object.
Parameters:
Name Type Description Defaultfile File File path or IO.
required*args Any Additional arguments passed to open. Defaults to ().
() **kwargs Any Any Additional keyword arguments passed to open. Defaults to {}.
{} Yields:
Type DescriptionGenerator[IOBase | IO, Any, Any] Examples:
Python Console Session>>> with FlatDict.open(\"tests/test.yaml\") as fp:\n... print(fp.read())\na: 1\nb: 2\nc: 3\n>>> io = open(\"tests/test.yaml\")\n>>> with FlatDict.open(io) as fp:\n... print(fp.read())\na: 1\nb: 2\nc: 3\n>>> with FlatDict.open(123, mode=\"w\") as fp:\n... print(fp.read())\nTraceback (most recent call last):\nTypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\nchanfig/flat_dict.py Python@staticmethod\n@contextmanager\ndef open(file: File, *args: Any, encoding: str = \"utf-8\", **kwargs: Any) -> Generator[IOBase | IO, Any, Any]:\nr\"\"\"\n Open file IO from file path or IO.\n This methods extends the ability of built-in `open` by allowing it to accept an `IOBase` object.\n Args:\n file: File path or IO.\n *args: Additional arguments passed to `open`.\n Defaults to ().\n **kwargs: Any\n Additional keyword arguments passed to `open`.\n Defaults to {}.\n Yields:\n (Generator[IOBase | IO, Any, Any]):\n Examples:\n >>> with FlatDict.open(\"tests/test.yaml\") as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> io = open(\"tests/test.yaml\")\n >>> with FlatDict.open(io) as fp:\n ... print(fp.read())\n a: 1\n b: 2\n c: 3\n <BLANKLINE>\n >>> with FlatDict.open(123, mode=\"w\") as fp:\n ... print(fp.read())\n Traceback (most recent call last):\n TypeError: expected str, bytes, os.PathLike, IO or IOBase, not int\n \"\"\"\nif isinstance(file, (IOBase, IO)):\nyield file\nelif isinstance(file, (PathLike, str, bytes)):\ntry:\nfile = open(file, *args, encoding=encoding, **kwargs) # type: ignore # noqa: SIM115\nyield file # type: ignore\nfinally:\nwith suppress(Exception):\nfile.close() # type: ignore\nelse:\nraise TypeError(f\"expected str, bytes, os.PathLike, IO or IOBase, not {type(file).__name__}\")\nsave(file, method=None, *args, **kwargs)","text":"Save FlatDict to file.
Raises:
Type DescriptionValueError If save to IO and method is not specified.
TypeError If save to unsupported extension.
Alias:
saveExamples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.save(\"tests/test.yaml\")\n>>> d.save(\"test.conf\")\nTraceback (most recent call last):\nTypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"test.yaml\", \"w\") as f:\n... d.save(f)\nTraceback (most recent call last):\nValueError: `method` must be specified when saving to IO.\nchanfig/flat_dict.py Pythondef save(self, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.save(\"tests/test.yaml\")\n >>> d.save(\"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... d.save(f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif method is None:\nif isinstance(file, (IOBase, IO)):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nreturn self.yaml(file=file, *args, **kwargs) # type: ignore\nif extension in JSON:\nreturn self.json(file=file, *args, **kwargs) # type: ignore\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\")\nset(name, value)","text":"Set value of FlatDict.
Parameters:
Name Type Description Defaultname Any required value Any required Examples:
Python Console Session>>> d = FlatDict()\n>>> d.set('d', 1013)\n>>> d.get('d')\n1013\n>>> d['n'] = 'chang'\n>>> d.n\n'chang'\n>>> d.n = 'liu'\n>>> d['n']\n'liu'\nchanfig/flat_dict.py Pythondef set(self, name: Any, value: Any) -> None:\nr\"\"\"\n Set value of `FlatDict`.\n Args:\n name:\n value:\n Examples:\n >>> d = FlatDict()\n >>> d.set('d', 1013)\n >>> d.get('d')\n 1013\n >>> d['n'] = 'chang'\n >>> d.n\n 'chang'\n >>> d.n = 'liu'\n >>> d['n']\n 'liu'\n \"\"\"\nif name in self and isinstance(self.get(name), Variable):\nself.get(name).set(value)\nelse:\ndict.__setitem__(self, name, value)\nsetattr(name, value)","text":"Set attribute of FlatDict.
Note that it won\u2019t alter values in FlatDict.
Parameters:
Name Type Description Defaultname str required value Any required Warns:
Type DescriptionRuntimeWarning If name already exists in FlatDict.
Examples:
Python Console Session>>> d = FlatDict()\n>>> d.setattr('attr', 'value')\n>>> d.getattr('attr')\n'value'\n>>> d.set('d', 1013)\n>>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n>>> d.get('d')\n1013\n>>> d.d\n1013\n>>> d.getattr('d')\n1031\nchanfig/flat_dict.py Pythondef setattr(self, name: str, value: Any) -> None:\nr\"\"\"\n Set attribute of `FlatDict`.\n Note that it won't alter values in `FlatDict`.\n Args:\n name:\n value:\n Warns:\n RuntimeWarning: If name already exists in `FlatDict`.\n Examples:\n >>> d = FlatDict()\n >>> d.setattr('attr', 'value')\n >>> d.getattr('attr')\n 'value'\n >>> d.set('d', 1013)\n >>> d.setattr('d', 1031) # RuntimeWarning: d already exists in FlatDict.\n >>> d.get('d')\n 1013\n >>> d.d\n 1013\n >>> d.getattr('d')\n 1031\n \"\"\"\nif name in self:\nwarn(\nf\"{name} already exists in {self.__class__.__name__}.\\n\"\nf\"Users must call `{self.__class__.__name__}.getattr()` to retrieve conflicting attribute value.\",\nRuntimeWarning,\n)\nself.__dict__[name] = value\nsort(key=None, reverse=False)","text":"Sort FlatDict.
Returns:
Type DescriptionFlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.sort().dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> d = FlatDict(b=2, c=3, a=1)\n>>> d.sort().dict()\n{'a': 1, 'b': 2, 'c': 3}\n>>> a = [1]\n>>> d = FlatDict(z=0, a=a)\n>>> a.append(2)\n>>> d.sort().dict()\n{'a': [1, 2], 'z': 0}\nchanfig/flat_dict.py Pythondef sort(self, key: Callable | None = None, reverse: bool = False) -> FlatDict:\nr\"\"\"\n Sort `FlatDict`.\n Returns:\n (FlatDict):\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> d = FlatDict(b=2, c=3, a=1)\n >>> d.sort().dict()\n {'a': 1, 'b': 2, 'c': 3}\n >>> a = [1]\n >>> d = FlatDict(z=0, a=a)\n >>> a.append(2)\n >>> d.sort().dict()\n {'a': [1, 2], 'z': 0}\n \"\"\"\nitems = sorted(self.items(), key=key, reverse=reverse)\nself.clear()\nfor k, v in items:\nself[k] = v\nreturn self\nto(cls)","text":"Convert values of FlatDict to target cls.
Parameters:
Name Type Description Defaultcls str | device | dtype required Returns:
Name Type Descriptionself FlatDict Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.to(int)\nTraceback (most recent call last):\nTypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\nchanfig/flat_dict.py Pythondef to(self, cls: str | TorchDevice | TorchDType) -> FlatDict: # pragma: no cover\nr\"\"\"\n Convert values of `FlatDict` to target `cls`.\n Args:\n cls (str | torch.device | torch.dtype):\n Returns:\n self:\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.to(int)\n Traceback (most recent call last):\n TypeError: to() only support torch.dtype and torch.device, but got <class 'int'>.\n \"\"\"\n# pylint: disable=C0103\nif isinstance(cls, (str, TorchDevice, TorchDType)):\nfor k, v in self.all_items():\nif hasattr(v, \"to\"):\nself[k] = v.to(cls)\nreturn self\nraise TypeError(f\"to() only support torch.dtype and torch.device, but got {cls}.\")\ntpu()","text":"Move all tensors to tpu.
Returns:
Name Type Descriptionself FlatDict Alias:
xlaExamples:
Python Console Session>>> import torch\n>>> d = FlatDict(a=torch.tensor(1))\n>>> d.tpu().dict()\n{'a': tensor(1, device='xla:0')}\n>>> d.xla().dict() # alias\n{'a': tensor(1, device='xla:0')}\nchanfig/flat_dict.py Pythondef tpu(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Move all tensors to tpu.\n Returns:\n self:\n **Alias**:\n + `xla`\n Examples:\n >>> import torch\n >>> d = FlatDict(a=torch.tensor(1))\n >>> d.tpu().dict() # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n >>> d.xla().dict() # alias # doctest: +SKIP\n {'a': tensor(1, device='xla:0')}\n \"\"\"\nreturn self.to(TorchDevice(\"xla\"))\nunion(*args, **kwargs)","text":"Alias of merge.
chanfig/flat_dict.py Pythondef union(self, *args: Any, **kwargs: Any) -> FlatDict:\nr\"\"\"\n Alias of [`merge`][chanfig.FlatDict.merge].\n \"\"\"\nreturn self.merge(*args, **kwargs)\nvalidate()","text":"Validate FlatDict.
Raises:
Type DescriptionTypeError If value is not of the type declared in class annotations.
TypeError If Variable has invalid type.
ValueError If Variable has invalid value.
Examples:
Python Console Session>>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n>>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\nTraceback (most recent call last):\nTypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n>>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\nTraceback (most recent call last):\nValueError: 'n' has invalid value. Value chang is not valid.\nchanfig/flat_dict.py Pythondef validate(self) -> None:\nr\"\"\"\n Validate `FlatDict`.\n Raises:\n TypeError: If value is not of the type declared in class annotations.\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.islower()))\n >>> d = FlatDict(d=Variable(1016, type=str), n=Variable('chang', validator=lambda x: x.islower()))\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = FlatDict(d=Variable(1016, type=int), n=Variable('chang', validator=lambda x: x.isupper()))\n Traceback (most recent call last):\n ValueError: 'n' has invalid value. Value chang is not valid.\n \"\"\"\nself._validate(self)\nxla()","text":"Alias of tpu.
chanfig/flat_dict.py Pythondef xla(self) -> FlatDict: # pragma: no cover\nr\"\"\"\n Alias of [`tpu`][chanfig.FlatDict.tpu].\n \"\"\"\nreturn self.tpu()\nyaml(file, *args, **kwargs)","text":"Dump FlatDict to yaml file.
This method internally calls self.yamls() to generate yaml string. You may overwrite yamls in case something is not yaml serializable.
Examples:
Python Console Session>>> d = FlatDict(a=1, b=2, c=3)\n>>> d.yaml(\"tests/test.yaml\")\nchanfig/flat_dict.py Pythondef yaml(self, file: File, *args: Any, **kwargs: Any) -> None:\nr\"\"\"\n Dump `FlatDict` to yaml file.\n This method internally calls `self.yamls()` to generate yaml string.\n You may overwrite `yamls` in case something is not yaml serializable.\n Examples:\n >>> d = FlatDict(a=1, b=2, c=3)\n >>> d.yaml(\"tests/test.yaml\")\n \"\"\"\nwith self.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nself.yamls(fp, *args, **kwargs)\nyamls(*args, **kwargs)","text":"Dump FlatDict to yaml string.
Returns:
Type Descriptionstr Examples:
Python Console Session>>> FlatDict(a=1, b=2, c=3).yamls()\n'a: 1\\nb: 2\\nc: 3\\n'\nchanfig/flat_dict.py Pythondef yamls(self, *args: Any, **kwargs: Any) -> str:\nr\"\"\"\n Dump `FlatDict` to yaml string.\n Returns:\n (str):\n Examples:\n >>> FlatDict(a=1, b=2, c=3).yamls()\n 'a: 1\\nb: 2\\nc: 3\\n'\n \"\"\"\nkwargs.setdefault(\"Dumper\", YamlDumper)\nkwargs.setdefault(\"indent\", self.getattr(\"indent\", 2))\nreturn yaml_dump(self.dict(), *args, **kwargs) # type: ignore\nConvert an object to a dict.
Note that when converting a set object, it may be converted to a tuple object if its values is not hashable.
Parameters:
Name Type Description Defaultobj Any Object to be converted.
requiredReturns:
Type DescriptionMapping[str, Any] A dict.
Examples:
Python Console Session>>> to_dict(1)\n1\n>>> to_dict([1, 2, 3])\n[1, 2, 3]\n>>> to_dict((1, 2, 3))\n(1, 2, 3)\n>>> to_dict({1, 2, 3})\n{1, 2, 3}\n>>> to_dict({'a': 1, 'b': 2})\n{'a': 1, 'b': 2}\n>>> to_dict(Variable(1))\n1\n>>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))\n{'a': [[[[[{'b': 1}]]]]]}\n>>> to_dict(FlatDict(a={FlatDict(b=1)}))\n{'a': ({'b': 1},)}\nchanfig/flat_dict.py Pythondef to_dict(obj: Any) -> Mapping[str, Any]: # pylint: disable=R0911\nr\"\"\"\n Convert an object to a dict.\n Note that when converting a `set` object, it may be converted to a `tuple` object if its values is not hashable.\n Args:\n obj: Object to be converted.\n Returns:\n A dict.\n Examples:\n >>> to_dict(1)\n 1\n >>> to_dict([1, 2, 3])\n [1, 2, 3]\n >>> to_dict((1, 2, 3))\n (1, 2, 3)\n >>> to_dict({1, 2, 3})\n {1, 2, 3}\n >>> to_dict({'a': 1, 'b': 2})\n {'a': 1, 'b': 2}\n >>> to_dict(Variable(1))\n 1\n >>> to_dict(FlatDict(a=[[[[[FlatDict(b=1)]]]]]))\n {'a': [[[[[{'b': 1}]]]]]}\n >>> to_dict(FlatDict(a={FlatDict(b=1)}))\n {'a': ({'b': 1},)}\n \"\"\"\nif isinstance(obj, Mapping):\nreturn {k: to_dict(v) for k, v in obj.items()}\nif isinstance(obj, list):\nreturn [to_dict(v) for v in obj] # type: ignore\nif isinstance(obj, tuple):\nreturn tuple(to_dict(v) for v in obj) # type: ignore\nif isinstance(obj, set):\ntry:\nreturn {to_dict(v) for v in obj} # type: ignore\nexcept TypeError:\nreturn tuple(to_dict(v) for v in obj) # type: ignore\nif isinstance(obj, Variable):\nreturn obj.value\nreturn obj\noptions: heading_level: 0
Save FlatDict to file.
Raises:
Type DescriptionValueError If save to IO and method is not specified.
TypeError If save to unsupported extension.
Alias:
saveExamples:
Python Console Session>>> obj = {\"a\": 1, \"b\": 2, \"c\": 3}\n>>> save(obj, \"test.yaml\")\n>>> save(obj, \"test.json\")\n>>> save(obj, \"test.conf\")\nTraceback (most recent call last):\nTypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n>>> with open(\"test.yaml\", \"w\") as f:\n... save(obj, f)\nTraceback (most recent call last):\nValueError: `method` must be specified when saving to IO.\nchanfig/functional.py Pythondef save(obj, file: File, method: str | None = None, *args: Any, **kwargs: Any) -> None: # pylint: disable=W1113\nr\"\"\"\n Save `FlatDict` to file.\n Raises:\n ValueError: If save to `IO` and `method` is not specified.\n TypeError: If save to unsupported extension.\n **Alias**:\n + `save`\n Examples:\n >>> obj = {\"a\": 1, \"b\": 2, \"c\": 3}\n >>> save(obj, \"test.yaml\")\n >>> save(obj, \"test.json\")\n >>> save(obj, \"test.conf\")\n Traceback (most recent call last):\n TypeError: `file='test.conf'` should be in ('json',) or ('yml', 'yaml'), but got conf.\n >>> with open(\"test.yaml\", \"w\") as f:\n ... save(obj, f)\n Traceback (most recent call last):\n ValueError: `method` must be specified when saving to IO.\n \"\"\"\nif isinstance(obj, FlatDict):\nreturn obj.save(file, method, *args, **kwargs)\ndata = to_dict(obj)\nif method is None:\nif isinstance(file, IOBase):\nraise ValueError(\"`method` must be specified when saving to IO.\")\nmethod = splitext(file)[-1][1:] # type: ignore\nextension = method.lower() # type: ignore\nif extension in YAML:\nwith FlatDict.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nyaml_dump(data, fp, *args, **kwargs)\nreturn\nif extension in JSON:\nwith FlatDict.open(file, mode=\"w\") as fp: # pylint: disable=C0103\nfp.write(json_dumps(data, *args, **kwargs))\nreturn\nraise TypeError(f\"`file={file!r}` should be in {JSON} or {YAML}, but got {extension}.\") # type: ignore\noptions: heading_level: 0
Load a file into a NestedDict.
This function simply calls NestedDict.load.
Parameters:
Name Type Description Defaultfile PathStr The file to load.
required*args Any The arguments to pass to NestedDict.load.
() **kwargs Any The keyword arguments to pass to NestedDict.load.
{} See Also load
Examples:
Python Console Session>>> from chanfig import load\n>>> config = load(\"tests/test.yaml\")\n>>> config\nNestedDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n)\nchanfig/functional.py Pythondef load(file: PathStr, cls: type = NestedDict, *args: Any, **kwargs: Any) -> NestedDict: # pylint: disable=W1113\nr\"\"\"\n Load a file into a `NestedDict`.\n This function simply calls `NestedDict.load`.\n Args:\n file: The file to load.\n *args: The arguments to pass to `NestedDict.load`.\n **kwargs: The keyword arguments to pass to `NestedDict.load`.\n See Also:\n [`load`][chanfig.FlatDict.load]\n Examples:\n >>> from chanfig import load\n >>> config = load(\"tests/test.yaml\")\n >>> config\n NestedDict(\n ('a'): 1\n ('b'): 2\n ('c'): 3\n )\n \"\"\"\nreturn cls.load(file, *args, **kwargs) # type: ignore\noptions: heading_level: 0
Apply func to all children of obj.
Note that this method is meant for non-in-place modification of obj and should return the original object.
Parameters:
Name Type Description Defaultobj Any Object to apply function.
requiredfunc Callable Function to be applied.
required*args Any Positional arguments to be passed to func.
() **kwargs Any Keyword arguments to be passed to func.
{} Returns:
Type DescriptionAny Return value of func.
apply_: Apply an in-place operation.
chanfig/nested_dict.py Pythondef apply(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Apply `func` to all children of `obj`.\n Note that this method is meant for non-in-place modification of `obj` and should return the original object.\n Args:\n obj: Object to apply function.\n func: Function to be applied.\n *args: Positional arguments to be passed to `func`.\n **kwargs: Keyword arguments to be passed to `func`.\n Returns:\n (Any): Return value of `func`.\n See Also:\n [`apply_`][chanfig.nested_dict.apply_]: Apply an in-place operation.\n \"\"\"\nif isinstance(obj, NestedDict):\nreturn obj.empty_like(**{k: apply(v, func, *args, **kwargs) for k, v in obj.items()})\nif isinstance(obj, Mapping):\nreturn {k: apply(v, func, *args, **kwargs) for k, v in obj.items()}\nif isinstance(obj, list):\nreturn [apply(v, func, *args, **kwargs) for v in obj]\nif isinstance(obj, tuple):\nreturn tuple(apply(v, func, *args, **kwargs) for v in obj)\nif isinstance(obj, set):\ntry:\nreturn {apply(v, func, *args, **kwargs) for v in obj}\nexcept TypeError:\ntuple(apply(v, func, *args, **kwargs) for v in obj)\nreturn func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)\noptions: heading_level: 0
Apply func to all children of obj.
Note that this method is meant for non-in-place modification of obj and should return a new object.
Parameters:
Name Type Description Defaultobj Any Object to apply function.
requiredfunc Callable Function to be applied.
required*args Any Positional arguments to be passed to func.
() **kwargs Any Keyword arguments to be passed to func.
{} Returns:
Type DescriptionAny Return value of func.
apply_: Apply a non-in-place operation.
chanfig/nested_dict.py Pythondef apply_(obj: Any, func: Callable, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Apply `func` to all children of `obj`.\n Note that this method is meant for non-in-place modification of `obj` and should return a new object.\n Args:\n obj: Object to apply function.\n func: Function to be applied.\n *args: Positional arguments to be passed to `func`.\n **kwargs: Keyword arguments to be passed to `func`.\n Returns:\n (Any): Return value of `func`.\n See Also:\n [`apply_`][chanfig.nested_dict.apply]: Apply a non-in-place operation.\n \"\"\"\nif isinstance(obj, Mapping):\nfor v in obj.values():\napply_(v, func, *args, **kwargs)\nif isinstance(obj, (list, tuple, set)):\nfor v in obj:\napply_(v, func, *args, **kwargs)\nreturn func(*args, **kwargs) if ismethod(func) else func(obj, *args, **kwargs)\noptions: heading_level: 0
"},{"location":"nested_dict/","title":"NestedDict","text":" Bases: DefaultDict
NestedDict further extends DefaultDict object by introducing a nested structure with delimiter. By default, delimiter is ., but it could be modified in subclass or by calling dict.setattr('delimiter', D).
d = NestedDict({\"a.b.c\": 1}) is equivalent to d = NestedDict({\"a\": {\"b\": {\"c\": 1}}}), and you can access members either by d[\"a.b.c\"] or more simply by d.a.b.c.
This behaviour allows you to pass keyword arguments to other functions as easy as func1(**d.func1).
Since NestedDict inherits from DefaultDict, it also supports default_factory. With default_factory, you can assign d.a.b.c = 1 without assign d.a = NestedDict() in the first place. Note that the constructor of NestedDict is different from DefaultDict, default_factory is not a positional argument, and must be set in a keyword argument.
NestedDict also introduce all_keys, all_values, all_items methods to get all keys, values, items respectively in the nested structure.
Attributes:
Name Type Descriptionconvert_mapping bool bool = False If True, all new values with type of Mapping will be converted to default_factory. If default_factory is Null, will create an empty instance via self.empty as default_factory.
delimiter str str = \u201c.\u201d Delimiter for nested structure.
NotesWhen convert_mapping specified, all new values with type of Mapping will be converted to default_factory. If default_factory is Null, will create an empty instance via self.empty as default_factory.
convert_mapping is automatically applied to arguments during initialisation.
Examples:
Python Console Session>>> NestedDict({\"f.n\": \"chang\"})\nNestedDict(\n ('f'): NestedDict(\n ('n'): 'chang'\n )\n)\n>>> d = NestedDict({\"f.n\": \"chang\"}, default_factory=NestedDict)\n>>> d.i.d = 1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.dict()\n{'f': {'n': 'chang'}, 'i': {'d': 1013}}\nchanfig/nested_dict.py Pythonclass NestedDict(DefaultDict): # type: ignore # pylint: disable=E1136\nr\"\"\"\n `NestedDict` further extends `DefaultDict` object by introducing a nested structure with `delimiter`.\n By default, `delimiter` is `.`, but it could be modified in subclass or by calling `dict.setattr('delimiter', D)`.\n `d = NestedDict({\"a.b.c\": 1})` is equivalent to `d = NestedDict({\"a\": {\"b\": {\"c\": 1}}})`,\n and you can access members either by `d[\"a.b.c\"]` or more simply by `d.a.b.c`.\n This behaviour allows you to pass keyword arguments to other functions as easy as `func1(**d.func1)`.\n Since `NestedDict` inherits from `DefaultDict`, it also supports `default_factory`.\n With `default_factory`, you can assign `d.a.b.c = 1` without assign `d.a = NestedDict()` in the first place.\n Note that the constructor of `NestedDict` is different from `DefaultDict`, `default_factory` is not a positional\n argument, and must be set in a keyword argument.\n `NestedDict` also introduce `all_keys`, `all_values`, `all_items` methods to get all keys, values, items\n respectively in the nested structure.\n Attributes:\n convert_mapping: bool = False\n If `True`, all new values with type of `Mapping` will be converted to `default_factory`.\n If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.\n delimiter: str = \".\"\n Delimiter for nested structure.\n Notes:\n When `convert_mapping` specified, all new values with type of `Mapping` will be converted to `default_factory`.\n If `default_factory` is `Null`, will create an empty instance via `self.empty` as `default_factory`.\n `convert_mapping` is automatically applied to arguments during initialisation.\n Examples:\n >>> NestedDict({\"f.n\": \"chang\"})\n NestedDict(\n ('f'): NestedDict(\n ('n'): 'chang'\n )\n )\n >>> d = NestedDict({\"f.n\": \"chang\"}, default_factory=NestedDict)\n >>> d.i.d = 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.dict()\n {'f': {'n': 'chang'}, 'i': {'d': 1013}}\n \"\"\"\nconvert_mapping: bool = False\ndelimiter: str = \".\"\nfallback: bool = False\ndef __init__(\nself,\n*args: Any,\ndefault_factory: Callable | None = None,\nconvert_mapping: bool | None = None,\nfallback: bool | None = None,\n**kwargs: Any,\n) -> None:\nsuper().__init__(default_factory)\nself.merge(*args, **kwargs)\nif convert_mapping is not None:\nself.setattr(\"convert_mapping\", convert_mapping)\nif fallback is not None:\nself.setattr(\"fallback\", fallback)\ndef all_keys(self) -> Generator:\nr\"\"\"\n Get all keys of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_keys())\n ['a', 'b.c', 'b.d']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_keys)\ndef all_keys(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_keys(value, key)\nelse:\nyield key\nreturn all_keys(self)\ndef all_values(self) -> Generator:\nr\"\"\"\n Get all values of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_values())\n [1, 2, 3]\n \"\"\"\nfor value in self.values():\nif isinstance(value, NestedDict):\nyield from value.all_values()\nelse:\nyield value\ndef all_items(self) -> Generator:\nr\"\"\"\n Get all items of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_items())\n [('a', 1), ('b.c', 2), ('b.d', 3)]\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_items)\ndef all_items(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_items(value, key)\nelse:\nyield key, value\nreturn all_items(self)\ndef apply(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for non-in-place modification of `obj`, for example, [`to`][chanfig.NestedDict.to].\n Args:\n func (Callable):\n See Also:\n [`apply_`][chanfig.NestedDict.apply_]: Apply an in-place operation.\n [`apply`][chanfig.nested_dict.apply]: Implementation of `apply`.\n tionples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply(func).dict()\n {'a': {}, 'b': [{}], 'c': ({},), 'd': ({},)}\n \"\"\"\nreturn apply(self, func, *args, **kwargs)\ndef apply_(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for in-place modification of `obj`, for example, [`freeze`][chanfig.Config.freeze].\n Args:\n func (Callable):\n See Also:\n [`apply`][chanfig.NestedDict.apply]: Apply a non-in-place operation.\n [`apply_`][chanfig.nested_dict.apply_]: Implementation of `apply_` method.\n Examples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply_(func).dict()\n {'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\n \"\"\"\napply_(self, func, *args, **kwargs)\nreturn self\ndef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `NestedDict`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `NestedDict` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('i.d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('a.b', None)\n >>> d.f\n NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n >>> del d.f\n >>> d = NestedDict({\"i.d\": 1013})\n >>> d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> d.e = {}\n >>> d.get('e.f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n >>> d.get('e.f')\n >>> d.get('e.f', 1)\n 1\n >>> d.e.f\n Traceback (most recent call last):\n AttributeError: 'dict' object has no attribute 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\nif fallback is None:\nfallback = self.getattr(\"fallback\", False)\nfallback_name = name.split(delimiter)[-1] if isinstance(name, str) else name\nfallback_values = []\ntry:\nwhile isinstance(name, str) and delimiter in name:\nif fallback and fallback_name in self:\nfallback_values.append(self.get(fallback_name))\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (KeyError, AttributeError, TypeError):\nif fallback and fallback_values:\nreturn fallback_values[-1]\nif default is not Null:\nreturn default\nraise KeyError(name) from None\nif (fallback and fallback_values) and (not isinstance(self, Iterable) or name not in self):\nreturn fallback_values[-1]\n# if value is a python dict\nif not isinstance(self, NestedDict):\nif name not in self and default is not Null:\nreturn default\nreturn self[name]\nreturn super().get(name, default)\ndef set( # pylint: disable=W0221\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `NestedDict`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Examples:\n >>> d = NestedDict(default_factory=NestedDict)\n >>> d.set('i.d', 1013)\n >>> d.get('i.d')\n 1013\n >>> d.dict()\n {'i': {'d': 1013}}\n >>> d['f.n'] = 'chang'\n >>> d.f.n\n 'chang'\n >>> d.n.l = 'liu'\n >>> d['n.l']\n 'liu'\n >>> d['f.n.e'] = \"error\"\n Traceback (most recent call last):\n ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n >>> d['f.n.e.a'] = \"error\"\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.f.n.e.a = \"error\"\n Traceback (most recent call last):\n AttributeError: 'str' object has no attribute 'e'\n >>> d.setattr('convert_mapping', True)\n >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.a.b.c.d\n 1\n >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.c.d['e.f']\n 2\n >>> d.setattr('convert_mapping', False)\n >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n >>> d['e.f']['c.d']\n 1\n \"\"\"\n# pylint: disable=W0642\nfull_name = name\ndelimiter = self.getattr(\"delimiter\", \".\")\nif convert_mapping is None:\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ndefault_factory = self.getattr(\"default_factory\", self.empty)\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif name in dir(self) and isinstance(getattr(self.__class__, name), (property, cached_property)):\nself, name = getattr(self, name), rest\nelif name not in self and isinstance(self, Mapping):\ndefault = (\nself.__missing__(name, default_factory()) if hasattr(self, \"__missing__\") else default_factory()\n)\nself, name = default, rest\nelse:\nself, name = self[name], rest\nif isinstance(self, NestedDict):\ndefault_factory = self.getattr(\"default_factory\", self.empty)\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif (\nconvert_mapping\nand isinstance(value, Mapping)\nand not isinstance(value, default_factory if isinstance(default_factory, type) else type(self))\nand not isinstance(value, Variable)\n):\ntry:\nvalue = default_factory(**value)\nexcept TypeError:\nvalue = default_factory(value)\nif isinstance(self, NestedDict):\nsuper().set(name, value)\nelif isinstance(self, Mapping):\ndict.__setitem__(self, name, value)\nelse:\nraise ValueError(\nf\"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`.\"\n)\ndef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `NestedDict`.\n Args:\n name:\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> d.dict()\n {'i': {}, 'f': {'n': 'chang'}}\n >>> d.i.d\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'd'\n >>> del d.f.n\n >>> d.dict()\n {'i': {}, 'f': {}}\n >>> d.f.n\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'n'\n >>> del d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> del d['f.n']\n Traceback (most recent call last):\n KeyError: 'n'\n >>> d.e = {'a': {'b': 1}}\n >>> del d['e.a.b']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\n# if value is a python dict\nif not isinstance(self, NestedDict):\ndel self[name]\nreturn\nsuper().delete(name)\ndef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `NestedDict`.\n Args:\n name:\n default:\n Returns:\n value: If `NestedDict` does not contain `name`, return `default`.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n >>> d.pop('i.d')\n 1013\n >>> d.pop('i.d', True)\n True\n >>> d.pop('i.d')\n Traceback (most recent call last):\n KeyError: 'd'\n >>> d.pop('e')\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.pop('e.f')\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif not isinstance(self, dict) or name not in self:\nif default is not Null:\nreturn default\nraise KeyError(name)\nreturn super().pop(name)\ndef validate(self) -> None:\nr\"\"\"\n Validate `NestedDict`.\n Raises:\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n >>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n ValueError: 'd' has invalid value. Value -1 is not valid.\n \"\"\"\nself.apply_(self._validate)\ndef sort(self, key: Callable | None = None, reverse: bool = False, recursive: bool = True) -> NestedDict:\nr\"\"\"\n Sort `NestedDict`.\n Args:\n recursive (bool): Whether to apply `sort` recursively.\n Returns:\n (NestedDict):\n Examples:\n >>> l = [1]\n >>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort(recursive=False).dict()\n {'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n >>> l.append(2)\n >>> d.b.e.f\n [1, 2]\n \"\"\"\nif recursive:\nfor value in self.values():\nif isinstance(value, FlatDict):\nvalue.sort(key=key, reverse=reverse)\nreturn super().sort(key=key, reverse=reverse) # type: ignore\n@staticmethod\ndef _merge(this: FlatDict, that: Iterable, overwrite: bool = True) -> Mapping:\nif not that:\nreturn this\nelif isinstance(that, Mapping):\nthat = that.items()\ncontext = this.converting() if isinstance(this, NestedDict) else nullcontext()\nwith context:\nfor key, value in that:\nif key in this and isinstance(this[key], Mapping):\nif isinstance(value, Mapping):\nNestedDict._merge(this[key], value, overwrite)\nelif overwrite:\nif isinstance(this, NestedDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nelif key in dir(this) and isinstance(getattr(this.__class__, key), (property, cached_property)):\ngetattr(this, key).merge(value, overwrite=overwrite)\nelif overwrite or key not in this:\nif isinstance(this, NestedDict):\nthis.set(key, value)\nelse:\nthis[key] = value\nreturn this\ndef intersect( # pylint: disable=W0221\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Intersection of `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.intersect(n).dict()\n {'c': {'d': {'e': 4, 'f': 5}}}\n >>> d.intersect(\"tests/test.yaml\").dict()\n {'a': 1}\n >>> d.intersect(n, recursive=False).dict()\n {}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.intersect(l).dict()\n {'a': 1}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._intersect(self, other, recursive)) # type: ignore\n@staticmethod\ndef _intersect(this: NestedDict, that: Iterable, recursive: bool = True) -> Mapping:\nret: NestedDict = NestedDict()\nfor key, value in that:\nif key in this:\nif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:\nintersects = this[key].intersect(value)\nif intersects:\nret[key] = intersects\nelif this[key] == value:\nret[key] = value\nreturn ret\ndef difference( # pylint: disable=W0221, C0103\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Difference between `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.difference(n).dict()\n {'b': {'c': 3, 'd': 5}, 'd': 0}\n >>> d.difference(\"tests/test.yaml\").dict()\n {'b': 2, 'c': 3}\n >>> d.difference(n, recursive=False).dict()\n {'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._difference(self, other, recursive)) # type: ignore\n@staticmethod\ndef _difference(this: NestedDict, that: Iterable, recursive: bool = True) -> Mapping:\nret: NestedDict = NestedDict()\nfor key, value in that:\nif key not in this:\nret[key] = value\nelif isinstance(this[key], NestedDict) and isinstance(value, Mapping) and recursive:\ndifferences = this[key].difference(value)\nif differences:\nret[key] = differences\nelif this[key] != value:\nret[key] = value\nreturn ret\n@contextmanager\ndef converting(self):\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ntry:\nself.setattr(\"convert_mapping\", True)\nyield\nfinally:\nself.setattr(\"convert_mapping\", convert_mapping)\ndef __contains__(self, name: Any) -> bool: # type: ignore\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif super().__contains__(name):\nself, name = self[name], rest # pylint: disable=W0642\nelse:\nreturn False\nreturn super().__contains__(name)\nexcept (TypeError, KeyError): # TypeError when name is not in self\nreturn False\nall_items()","text":"Get all items of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_items())\n[('a', 1), ('b.c', 2), ('b.d', 3)]\nchanfig/nested_dict.py Pythondef all_items(self) -> Generator:\nr\"\"\"\n Get all items of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_items())\n [('a', 1), ('b.c', 2), ('b.d', 3)]\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_items)\ndef all_items(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_items(value, key)\nelse:\nyield key, value\nreturn all_items(self)\nall_keys()","text":"Get all keys of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_keys())\n['a', 'b.c', 'b.d']\nchanfig/nested_dict.py Pythondef all_keys(self) -> Generator:\nr\"\"\"\n Get all keys of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_keys())\n ['a', 'b.c', 'b.d']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\n@wraps(self.all_keys)\ndef all_keys(self, prefix=\"\"):\nfor key, value in self.items():\nif prefix:\nkey = str(prefix) + str(delimiter) + str(key)\nif isinstance(value, NestedDict):\nyield from all_keys(value, key)\nelse:\nyield key\nreturn all_keys(self)\nall_values()","text":"Get all values of NestedDict.
Returns:
Type DescriptionGenerator Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n>>> list(d.all_values())\n[1, 2, 3]\nchanfig/nested_dict.py Pythondef all_values(self) -> Generator:\nr\"\"\"\n Get all values of `NestedDict`.\n Returns:\n (Generator):\n Examples:\n >>> d = NestedDict({'a': 1, 'b': {'c': 2, 'd': 3}})\n >>> list(d.all_values())\n [1, 2, 3]\n \"\"\"\nfor value in self.values():\nif isinstance(value, NestedDict):\nyield from value.all_values()\nelse:\nyield value\napply(func, *args, **kwargs)","text":"Recursively apply a function to NestedDict and its children.
This method is meant for non-in-place modification of obj, for example, to.
Parameters:
Name Type Description Defaultfunc Callable required See Also apply_: Apply an in-place operation. apply: Implementation of apply.
def func(d): \u2026 if isinstance(d, NestedDict): \u2026 d.t = 1 d = NestedDict() d.a = NestedDict() d.b = [NestedDict(),] d.c = (NestedDict(),) d.d = {NestedDict(),} d.apply(func).dict() {\u2018a\u2019: {}, \u2018b\u2019: [{}], \u2018c\u2019: ({},), \u2018d\u2019: ({},)}
Source code inchanfig/nested_dict.py Pythondef apply(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for non-in-place modification of `obj`, for example, [`to`][chanfig.NestedDict.to].\n Args:\n func (Callable):\n See Also:\n [`apply_`][chanfig.NestedDict.apply_]: Apply an in-place operation.\n [`apply`][chanfig.nested_dict.apply]: Implementation of `apply`.\n tionples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply(func).dict()\n {'a': {}, 'b': [{}], 'c': ({},), 'd': ({},)}\n \"\"\"\nreturn apply(self, func, *args, **kwargs)\napply_(func, *args, **kwargs)","text":"Recursively apply a function to NestedDict and its children.
This method is meant for in-place modification of obj, for example, freeze.
Parameters:
Name Type Description Defaultfunc Callable required See Also apply: Apply a non-in-place operation. apply_: Implementation of apply_ method.
Examples:
Python Console Session>>> def func(d):\n... if isinstance(d, NestedDict):\n... d.t = 1\n>>> d = NestedDict()\n>>> d.a = NestedDict()\n>>> d.b = [NestedDict(),]\n>>> d.c = (NestedDict(),)\n>>> d.d = {NestedDict(),}\n>>> d.apply_(func).dict()\n{'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\nchanfig/nested_dict.py Pythondef apply_(self, func: Callable, *args: Any, **kwargs: Any) -> NestedDict:\nr\"\"\"\n Recursively apply a function to `NestedDict` and its children.\n Note:\n This method is meant for in-place modification of `obj`, for example, [`freeze`][chanfig.Config.freeze].\n Args:\n func (Callable):\n See Also:\n [`apply`][chanfig.NestedDict.apply]: Apply a non-in-place operation.\n [`apply_`][chanfig.nested_dict.apply_]: Implementation of `apply_` method.\n Examples:\n >>> def func(d):\n ... if isinstance(d, NestedDict):\n ... d.t = 1\n >>> d = NestedDict()\n >>> d.a = NestedDict()\n >>> d.b = [NestedDict(),]\n >>> d.c = (NestedDict(),)\n >>> d.d = {NestedDict(),}\n >>> d.apply_(func).dict()\n {'a': {'t': 1}, 'b': [{'t': 1}], 'c': ({'t': 1},), 'd': ({'t': 1},), 't': 1}\n \"\"\"\napply_(self, func, *args, **kwargs)\nreturn self\ndelete(name)","text":"Delete value from NestedDict.
Parameters:
Name Type Description Defaultname Any required Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n>>> d.i.d\n1013\n>>> d.f.n\n'chang'\n>>> d.delete('i.d')\n>>> d.dict()\n{'i': {}, 'f': {'n': 'chang'}}\n>>> d.i.d\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'd'\n>>> del d.f.n\n>>> d.dict()\n{'i': {}, 'f': {}}\n>>> d.f.n\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'n'\n>>> del d.e\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'e'\n>>> del d['f.n']\nTraceback (most recent call last):\nKeyError: 'n'\n>>> d.e = {'a': {'b': 1}}\n>>> del d['e.a.b']\nchanfig/nested_dict.py Pythondef delete(self, name: Any) -> None:\nr\"\"\"\n Delete value from `NestedDict`.\n Args:\n name:\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\"})\n >>> d.i.d\n 1013\n >>> d.f.n\n 'chang'\n >>> d.delete('i.d')\n >>> d.dict()\n {'i': {}, 'f': {'n': 'chang'}}\n >>> d.i.d\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'd'\n >>> del d.f.n\n >>> d.dict()\n {'i': {}, 'f': {}}\n >>> d.f.n\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'n'\n >>> del d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> del d['f.n']\n Traceback (most recent call last):\n KeyError: 'n'\n >>> d.e = {'a': {'b': 1}}\n >>> del d['e.a.b']\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\n# if value is a python dict\nif not isinstance(self, NestedDict):\ndel self[name]\nreturn\nsuper().delete(name)\ndifference(other, recursive=True)","text":"Difference between NestedDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required recursive bool True Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n>>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n>>> d.difference(n).dict()\n{'b': {'c': 3, 'd': 5}, 'd': 0}\n>>> d.difference(\"tests/test.yaml\").dict()\n{'b': 2, 'c': 3}\n>>> d.difference(n, recursive=False).dict()\n{'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n>>> l = [('a', 1), ('d', 4)]\n>>> d.difference(l).dict()\n{'d': 4}\n>>> d.difference(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\nchanfig/nested_dict.py Pythondef difference( # pylint: disable=W0221, C0103\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Difference between `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.difference(n).dict()\n {'b': {'c': 3, 'd': 5}, 'd': 0}\n >>> d.difference(\"tests/test.yaml\").dict()\n {'b': 2, 'c': 3}\n >>> d.difference(n, recursive=False).dict()\n {'b': {'c': 3, 'd': 5}, 'c': {'d': {'e': 4, 'f': 5}}, 'd': 0}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.difference(l).dict()\n {'d': 4}\n >>> d.difference(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._difference(self, other, recursive)) # type: ignore\nget(name, default=None, fallback=None)","text":"Get value from NestedDict.
Note that default has higher priority than default_factory.
Parameters:
Name Type Description Defaultname Any required default Any None Returns:
Name Type Descriptionvalue Any If NestedDict does not contain name, return default. If default is not specified, return default_factory().
Raises:
Type DescriptionKeyError If NestedDict does not contain name and default/default_factory is not specified.
TypeError If name is not hashable.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n>>> d.get('i.d')\n1013\n>>> d['i.d']\n1013\n>>> d.i.d\n1013\n>>> d.get('i.d', None)\n1013\n>>> d.get('f', 2)\n2\n>>> d.get('a.b', None)\n>>> d.f\nNestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n>>> del d.f\n>>> d = NestedDict({\"i.d\": 1013})\n>>> d.e\nTraceback (most recent call last):\nAttributeError: 'NestedDict' object has no attribute 'e'\n>>> d.e = {}\n>>> d.get('e.f', Null)\nTraceback (most recent call last):\nKeyError: 'f'\n>>> d.get('e.f')\n>>> d.get('e.f', 1)\n1\n>>> d.e.f\nTraceback (most recent call last):\nAttributeError: 'dict' object has no attribute 'f'\nchanfig/nested_dict.py Pythondef get(self, name: Any, default: Any = None, fallback: bool | None = None) -> Any:\nr\"\"\"\n Get value from `NestedDict`.\n Note that `default` has higher priority than `default_factory`.\n Args:\n name:\n default:\n Returns:\n value:\n If `NestedDict` does not contain `name`, return `default`.\n If `default` is not specified, return `default_factory()`.\n Raises:\n KeyError: If `NestedDict` does not contain `name` and `default`/`default_factory` is not specified.\n TypeError: If `name` is not hashable.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013}, default_factory=NestedDict)\n >>> d.get('i.d')\n 1013\n >>> d['i.d']\n 1013\n >>> d.i.d\n 1013\n >>> d.get('i.d', None)\n 1013\n >>> d.get('f', 2)\n 2\n >>> d.get('a.b', None)\n >>> d.f\n NestedDict(<class 'chanfig.nested_dict.NestedDict'>, )\n >>> del d.f\n >>> d = NestedDict({\"i.d\": 1013})\n >>> d.e\n Traceback (most recent call last):\n AttributeError: 'NestedDict' object has no attribute 'e'\n >>> d.e = {}\n >>> d.get('e.f', Null)\n Traceback (most recent call last):\n KeyError: 'f'\n >>> d.get('e.f')\n >>> d.get('e.f', 1)\n 1\n >>> d.e.f\n Traceback (most recent call last):\n AttributeError: 'dict' object has no attribute 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\nif fallback is None:\nfallback = self.getattr(\"fallback\", False)\nfallback_name = name.split(delimiter)[-1] if isinstance(name, str) else name\nfallback_values = []\ntry:\nwhile isinstance(name, str) and delimiter in name:\nif fallback and fallback_name in self:\nfallback_values.append(self.get(fallback_name))\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (KeyError, AttributeError, TypeError):\nif fallback and fallback_values:\nreturn fallback_values[-1]\nif default is not Null:\nreturn default\nraise KeyError(name) from None\nif (fallback and fallback_values) and (not isinstance(self, Iterable) or name not in self):\nreturn fallback_values[-1]\n# if value is a python dict\nif not isinstance(self, NestedDict):\nif name not in self and default is not Null:\nreturn default\nreturn self[name]\nreturn super().get(name, default)\nintersect(other, recursive=True)","text":"Intersection of NestedDict and other.
Parameters:
Name Type Description Defaultother Mapping | Iterable | PathStr required recursive bool True Examples:
Python Console Session>>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n>>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n>>> d.intersect(n).dict()\n{'c': {'d': {'e': 4, 'f': 5}}}\n>>> d.intersect(\"tests/test.yaml\").dict()\n{'a': 1}\n>>> d.intersect(n, recursive=False).dict()\n{}\n>>> l = [('a', 1), ('d', 4)]\n>>> d.intersect(l).dict()\n{'a': 1}\n>>> d.intersect(1)\nTraceback (most recent call last):\nTypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\nchanfig/nested_dict.py Pythondef intersect( # pylint: disable=W0221\nself, other: Mapping | Iterable | PathStr, recursive: bool = True\n) -> NestedDict:\nr\"\"\"\n Intersection of `NestedDict` and `other`.\n Args:\n other (Mapping | Iterable | PathStr):\n recursive (bool):\n Examples:\n >>> d = NestedDict({'a': 1, 'b.c': 2, 'b.d': 3, 'c.d.e': 4, 'c.d.f': 5, 'c.e': 6})\n >>> n = {'b': {'c': 3, 'd': 5}, 'c.d.e': 4, 'c.d': {'f': 5}, 'd': 0}\n >>> d.intersect(n).dict()\n {'c': {'d': {'e': 4, 'f': 5}}}\n >>> d.intersect(\"tests/test.yaml\").dict()\n {'a': 1}\n >>> d.intersect(n, recursive=False).dict()\n {}\n >>> l = [('a', 1), ('d', 4)]\n >>> d.intersect(l).dict()\n {'a': 1}\n >>> d.intersect(1)\n Traceback (most recent call last):\n TypeError: `other=1` should be of type Mapping, Iterable or PathStr, but got <class 'int'>.\n \"\"\"\nif isinstance(other, (PathLike, str, bytes)):\nother = self.load(other)\nif isinstance(other, (Mapping,)):\nother = self.empty(other).items()\nif not isinstance(other, Iterable):\nraise TypeError(f\"`other={other}` should be of type Mapping, Iterable or PathStr, but got {type(other)}.\")\nreturn self.empty(self._intersect(self, other, recursive)) # type: ignore\npop(name, default=Null)","text":"Pop value from NestedDict.
Parameters:
Name Type Description Defaultname Any required default Any Null Returns:
Name Type Descriptionvalue Any If NestedDict does not contain name, return default.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n>>> d.pop('i.d')\n1013\n>>> d.pop('i.d', True)\nTrue\n>>> d.pop('i.d')\nTraceback (most recent call last):\nKeyError: 'd'\n>>> d.pop('e')\nTraceback (most recent call last):\nKeyError: 'e'\n>>> d.pop('e.f')\nTraceback (most recent call last):\nKeyError: 'f'\nchanfig/nested_dict.py Pythondef pop(self, name: Any, default: Any = Null) -> Any:\nr\"\"\"\n Pop value from `NestedDict`.\n Args:\n name:\n default:\n Returns:\n value: If `NestedDict` does not contain `name`, return `default`.\n Examples:\n >>> d = NestedDict({\"i.d\": 1013, \"f.n\": \"chang\", \"n.a.b.c\": 1}, default_factory=NestedDict)\n >>> d.pop('i.d')\n 1013\n >>> d.pop('i.d', True)\n True\n >>> d.pop('i.d')\n Traceback (most recent call last):\n KeyError: 'd'\n >>> d.pop('e')\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.pop('e.f')\n Traceback (most recent call last):\n KeyError: 'f'\n \"\"\"\ndelimiter = self.getattr(\"delimiter\", \".\")\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nself, name = self[name], rest # pylint: disable=W0642\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif not isinstance(self, dict) or name not in self:\nif default is not Null:\nreturn default\nraise KeyError(name)\nreturn super().pop(name)\nset(name, value, convert_mapping=None)","text":"Set value of NestedDict.
Parameters:
Name Type Description Defaultname Any required value Any required convert_mapping bool | None Whether to convert Mapping to NestedDict. Defaults to self.convert_mapping.
None Examples:
Python Console Session>>> d = NestedDict(default_factory=NestedDict)\n>>> d.set('i.d', 1013)\n>>> d.get('i.d')\n1013\n>>> d.dict()\n{'i': {'d': 1013}}\n>>> d['f.n'] = 'chang'\n>>> d.f.n\n'chang'\n>>> d.n.l = 'liu'\n>>> d['n.l']\n'liu'\n>>> d['f.n.e'] = \"error\"\nTraceback (most recent call last):\nValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n>>> d['f.n.e.a'] = \"error\"\nTraceback (most recent call last):\nKeyError: 'e'\n>>> d.f.n.e.a = \"error\"\nTraceback (most recent call last):\nAttributeError: 'str' object has no attribute 'e'\n>>> d.setattr('convert_mapping', True)\n>>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n>>> d.a.b.c.d\n1\n>>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n>>> d.c.d['e.f']\n2\n>>> d.setattr('convert_mapping', False)\n>>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n>>> d['e.f']['c.d']\n1\nchanfig/nested_dict.py Pythondef set( # pylint: disable=W0221\nself,\nname: Any,\nvalue: Any,\nconvert_mapping: bool | None = None,\n) -> None:\nr\"\"\"\n Set value of `NestedDict`.\n Args:\n name:\n value:\n convert_mapping: Whether to convert `Mapping` to `NestedDict`.\n Defaults to self.convert_mapping.\n Examples:\n >>> d = NestedDict(default_factory=NestedDict)\n >>> d.set('i.d', 1013)\n >>> d.get('i.d')\n 1013\n >>> d.dict()\n {'i': {'d': 1013}}\n >>> d['f.n'] = 'chang'\n >>> d.f.n\n 'chang'\n >>> d.n.l = 'liu'\n >>> d['n.l']\n 'liu'\n >>> d['f.n.e'] = \"error\"\n Traceback (most recent call last):\n ValueError: Cannot set `f.n.e` to `error`, as `f.n=chang`.\n >>> d['f.n.e.a'] = \"error\"\n Traceback (most recent call last):\n KeyError: 'e'\n >>> d.f.n.e.a = \"error\"\n Traceback (most recent call last):\n AttributeError: 'str' object has no attribute 'e'\n >>> d.setattr('convert_mapping', True)\n >>> d.a.b = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.a.b.c.d\n 1\n >>> d['c.d'] = {'c': {'d': 1}, 'e.f' : 2}\n >>> d.c.d['e.f']\n 2\n >>> d.setattr('convert_mapping', False)\n >>> d.set('e.f', {'c': {'d': 1}, 'e.f' : 2}, convert_mapping=True)\n >>> d['e.f']['c.d']\n 1\n \"\"\"\n# pylint: disable=W0642\nfull_name = name\ndelimiter = self.getattr(\"delimiter\", \".\")\nif convert_mapping is None:\nconvert_mapping = self.getattr(\"convert_mapping\", False)\ndefault_factory = self.getattr(\"default_factory\", self.empty)\ntry:\nwhile isinstance(name, str) and delimiter in name:\nname, rest = name.split(delimiter, 1)\nif name in dir(self) and isinstance(getattr(self.__class__, name), (property, cached_property)):\nself, name = getattr(self, name), rest\nelif name not in self and isinstance(self, Mapping):\ndefault = (\nself.__missing__(name, default_factory()) if hasattr(self, \"__missing__\") else default_factory()\n)\nself, name = default, rest\nelse:\nself, name = self[name], rest\nif isinstance(self, NestedDict):\ndefault_factory = self.getattr(\"default_factory\", self.empty)\nexcept (AttributeError, TypeError):\nraise KeyError(name) from None\nif (\nconvert_mapping\nand isinstance(value, Mapping)\nand not isinstance(value, default_factory if isinstance(default_factory, type) else type(self))\nand not isinstance(value, Variable)\n):\ntry:\nvalue = default_factory(**value)\nexcept TypeError:\nvalue = default_factory(value)\nif isinstance(self, NestedDict):\nsuper().set(name, value)\nelif isinstance(self, Mapping):\ndict.__setitem__(self, name, value)\nelse:\nraise ValueError(\nf\"Cannot set `{full_name}` to `{value}`, as `{delimiter.join(full_name.split(delimiter)[:-1])}={self}`.\"\n)\nsort(key=None, reverse=False, recursive=True)","text":"Sort NestedDict.
Parameters:
Name Type Description Defaultrecursive bool Whether to apply sort recursively.
True Returns:
Type DescriptionNestedDict Examples:
Python Console Session>>> l = [1]\n>>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n>>> d.sort().dict()\n{'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n>>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n>>> d.sort().dict()\n{'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n>>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n>>> d.sort(recursive=False).dict()\n{'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n>>> l.append(2)\n>>> d.b.e.f\n[1, 2]\nchanfig/nested_dict.py Pythondef sort(self, key: Callable | None = None, reverse: bool = False, recursive: bool = True) -> NestedDict:\nr\"\"\"\n Sort `NestedDict`.\n Args:\n recursive (bool): Whether to apply `sort` recursively.\n Returns:\n (NestedDict):\n Examples:\n >>> l = [1]\n >>> d = NestedDict({\"a\": 1, \"b\": {\"c\": 2, \"d\": 3}, \"b.e.f\": l})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort().dict()\n {'a': 1, 'b': {'c': 2, 'd': 3, 'e': {'f': [1]}}}\n >>> d = NestedDict({\"b.e.f\": l, \"b.d\": 3, \"a\": 1, \"b.c\": 2})\n >>> d.sort(recursive=False).dict()\n {'a': 1, 'b': {'e': {'f': [1]}, 'd': 3, 'c': 2}}\n >>> l.append(2)\n >>> d.b.e.f\n [1, 2]\n \"\"\"\nif recursive:\nfor value in self.values():\nif isinstance(value, FlatDict):\nvalue.sort(key=key, reverse=reverse)\nreturn super().sort(key=key, reverse=reverse) # type: ignore\nvalidate()","text":"Validate NestedDict.
Raises:
Type DescriptionTypeError If Variable has invalid type.
ValueError If Variable has invalid value.
Examples:
Python Console Session>>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n>>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\nTraceback (most recent call last):\nTypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n>>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\nTraceback (most recent call last):\nValueError: 'd' has invalid value. Value -1 is not valid.\nchanfig/nested_dict.py Pythondef validate(self) -> None:\nr\"\"\"\n Validate `NestedDict`.\n Raises:\n TypeError: If `Variable` has invalid type.\n ValueError: If `Variable` has invalid value.\n Examples:\n >>> d = NestedDict({\"i.d\": Variable(1016, type=int, validator=lambda x: x > 0)})\n >>> d = NestedDict({\"i.d\": Variable(1016, type=str, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n TypeError: 'd' has invalid type. Value 1016 is not of type <class 'str'>.\n >>> d = NestedDict({\"i.d\": Variable(-1, type=int, validator=lambda x: x > 0)})\n Traceback (most recent call last):\n ValueError: 'd' has invalid value. Value -1 is not valid.\n \"\"\"\nself.apply_(self._validate)\n Bases: ArgumentParser
Parser to parse command-line arguments for CHANfiG.
ConfigParser is a subclass of argparse.ArgumentParser. It provides a new parse method to parse command-line arguments to CHANfiG.Config object.
Different to ArgumentParser.parse_args, ConfigParser.parse will try to parse any command-line arguments, even if they are not pre-defined by ArgumentParser.add_argument. This allows to relief the burden of adding tons of arguments for each tuneable parameter. In the meantime, there is no mechanism to notify you if you made a typo in command-line arguments.
Note that ArgumentParser.parse_args method is not overridden in ConfigParser. This is because it is still possible to construct CHANfiG.Config with ArgumentParser.parse_args, which has strict checking on command-line arguments.
chanfig/parser.py Pythonclass ConfigParser(ArgumentParser): # pylint: disable=C0115\nr\"\"\"\n Parser to parse command-line arguments for CHANfiG.\n `ConfigParser` is a subclass of `argparse.ArgumentParser`.\n It provides a new `parse` method to parse command-line arguments to `CHANfiG.Config` object.\n Different to `ArgumentParser.parse_args`, `ConfigParser.parse` will try to parse any command-line arguments,\n even if they are not pre-defined by `ArgumentParser.add_argument`.\n This allows to relief the burden of adding tons of arguments for each tuneable parameter.\n In the meantime, there is no mechanism to notify you if you made a typo in command-line arguments.\n Note that `ArgumentParser.parse_args` method is not overridden in `ConfigParser`.\n This is because it is still possible to construct `CHANfiG.Config` with `ArgumentParser.parse_args`,\n which has strict checking on command-line arguments.\n \"\"\"\ndef __init__(self, *args: Any, **kwargs: Any):\nsuper().__init__(*args, **kwargs)\nself._registries[\"action\"][None] = StoreAction\nself._registries[\"action\"][\"store\"] = StoreAction\ndef parse_args( # type: ignore\nself, args: Sequence[str] | None = None, namespace: Namespace | None = None\n) -> NestedDict:\nparsed = super().parse_args(args, namespace)\nif isinstance(parsed, Namespace):\nparsed = vars(parsed) # type: ignore\nif not isinstance(parsed, NestedDict):\nparsed = NestedDict({key: value for key, value in parsed.items() if value is not Null}) # type: ignore\nfor key, value in parsed.all_items():\nwith suppress(TypeError, ValueError, SyntaxError):\nvalue = literal_eval(value)\nparsed[key] = value\nreturn parsed # type: ignore\ndef parse( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | NestedDict | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse_config`][chanfig.ConfigParser.parse_config]: Only parse valid config arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n {'i': {'d': 1013}, 'f': {'n': 'chang'}}\n Values in command line overrides values in `default_config` file.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n {'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n Values in `default_config` file overrides values in `Config` object.\n >>> p = ConfigParser()\n >>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n {'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n ValueError will be raised when `default_config` is specified but not presented in command line.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config').dict()\n Traceback (most recent call last):\n RuntimeError: default_config is set to config, but not found in args.\n ValueError will be suppressed when `default_config` is specified bug not presented in command line,\n and `no_default_config_action` is set to `ignore` or `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n {'a': 2}\n ValueError will be raised when `no_default_config_action` is not in `raise`, `ignore`, and `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\n Traceback (most recent call last):\n ValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nfrom .config import Config # pylint: disable=C0415\nconfig = Config()\nelse:\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\n# add the command-line arguments\nkey_value_args = []\nfor arg in args:\nif args == \"--\":\nbreak\nif arg.startswith(\"--\"):\nkey_value_args.append(arg.split(\"=\", maxsplit=1))\nelse:\nif not key_value_args:\ncontinue\nkey_value_args[-1].append(arg)\nfor key_value in key_value_args:\nif key_value[0] not in self:\nif len(key_value) > 2:\nself.add_argument(key_value[0], nargs=\"+\")\nelse:\nself.add_argument(key_value[0])\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\ndef parse_config( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse`][chanfig.ConfigParser.parse]: Parse all command-line arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n {'a': 1}\n You can only parse argument that is defined in `Config`.\n error: unrecognized arguments: --b 1\n >>> p = ConfigParser()\n >>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict() # doctest: +SKIP\n Traceback (most recent call last):\n SystemExit: 2\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nraise ValueError(\"config must be specified\")\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\ndef add_config_arguments(self, config):\nfor key, value in config.all_items():\nif isinstance(value, Variable):\ndtype = value._type or value.dtype # pylint: disable=W0212\nelif value is not None:\ndtype = type(value)\nelse:\ndtype = None\nname = \"--\" + key\nif name not in self:\nhelp = value._help if isinstance(value, Variable) else None # pylint: disable=W0212,W0622\nif isinstance(value, (list, tuple, dict, set)):\nself.add_argument(name, type=dtype, nargs=\"+\", help=help, dest=key)\nelse:\nself.add_argument(name, type=dtype, help=help, dest=key)\ndef merge_default_config(self, parsed, default_config: str, no_default_config_action: str = \"raise\") -> NestedDict:\nmessage = f\"default_config is set to {default_config}, but not found in args.\"\nif default_config in parsed:\npath = parsed[default_config]\nwarn(f\"Config has 'default_config={path}' specified, its values will override values in Config\")\nreturn NestedDict.load(path).merge(parsed) # type: ignore\nif no_default_config_action == \"ignore\":\npass\nelif no_default_config_action == \"warn\":\nwarn(message, category=RuntimeWarning, stacklevel=2)\nelse:\nraise RuntimeError(message)\nreturn parsed\n@staticmethod\ndef identity(string):\nr\"\"\"\n https://stackoverflow.com/questions/69896931/cant-pickle-local-object-argumentparser-init-locals-identity\n \"\"\"\nreturn string\ndef __contains__(self, name: str):\nif name in self._option_string_actions:\nreturn True\nreturn False\nidentity(string) staticmethod","text":"Source code in chanfig/parser.py Python@staticmethod\ndef identity(string):\nr\"\"\"\n https://stackoverflow.com/questions/69896931/cant-pickle-local-object-argumentparser-init-locals-identity\n \"\"\"\nreturn string\nparse(args=None, config=None, default_config=None, no_default_config_action='raise')","text":"Parse the arguments for Config.
You may optionally specify a name for default_config, and CHANfiG will read the file under this name.
There are three levels of config:
Config parsed into this method,default_config (if specified),Higher levels override lower levels (i.e. 3 > 2 > 1).
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to Config.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' Returns:
Name Type Descriptionconfig Config The parsed Config.
Raises:
Type DescriptionValueError If default_config is specified but not found in args, and no_default_config_action is neither warn nor ignore.
ValueError If no_default_config_action is not in raise, warn and ignore.
parse_config: Only parse valid config arguments.
Examples:
Note that all examples uses NestedDict instead of Config for avoiding circular import.
Python Console Session>>> p = ConfigParser()\n>>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n{'i': {'d': 1013}, 'f': {'n': 'chang'}}\nValues in command line overrides values in default_config file.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n{'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\nValues in default_config file overrides values in Config object.
>>> p = ConfigParser()\n>>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n{'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\nValueError will be raised when default_config is specified but not presented in command line.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config').dict()\nTraceback (most recent call last):\nRuntimeError: default_config is set to config, but not found in args.\nValueError will be suppressed when default_config is specified bug not presented in command line, and no_default_config_action is set to ignore or warn.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n{'a': 2}\nValueError will be raised when no_default_config_action is not in raise, ignore, and warn.
>>> p = ConfigParser()\n>>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\nTraceback (most recent call last):\nValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\nchanfig/parser.py Pythondef parse( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | NestedDict | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse_config`][chanfig.ConfigParser.parse_config]: Only parse valid config arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse(['--i.d', '1013', '--f.n', 'chang']).dict()\n {'i': {'d': 1013}, 'f': {'n': 'chang'}}\n Values in command line overrides values in `default_config` file.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2', '--config', 'tests/test.yaml'], default_config='config').dict()\n {'a': 2, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n Values in `default_config` file overrides values in `Config` object.\n >>> p = ConfigParser()\n >>> p.parse(['--config', 'tests/test.yaml'], config=NestedDict(a=2), default_config='config').dict()\n {'a': 1, 'b': 2, 'c': 3, 'config': 'tests/test.yaml'}\n ValueError will be raised when `default_config` is specified but not presented in command line.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config').dict()\n Traceback (most recent call last):\n RuntimeError: default_config is set to config, but not found in args.\n ValueError will be suppressed when `default_config` is specified bug not presented in command line,\n and `no_default_config_action` is set to `ignore` or `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='ignore').dict()\n {'a': 2}\n ValueError will be raised when `no_default_config_action` is not in `raise`, `ignore`, and `warn`.\n >>> p = ConfigParser()\n >>> p.parse(['--a', '2'], default_config='config', no_default_config_action='suppress').dict()\n Traceback (most recent call last):\n ValueError: no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got suppress\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nfrom .config import Config # pylint: disable=C0415\nconfig = Config()\nelse:\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\n# add the command-line arguments\nkey_value_args = []\nfor arg in args:\nif args == \"--\":\nbreak\nif arg.startswith(\"--\"):\nkey_value_args.append(arg.split(\"=\", maxsplit=1))\nelse:\nif not key_value_args:\ncontinue\nkey_value_args[-1].append(arg)\nfor key_value in key_value_args:\nif key_value[0] not in self:\nif len(key_value) > 2:\nself.add_argument(key_value[0], nargs=\"+\")\nelse:\nself.add_argument(key_value[0])\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\nparse_config(args=None, config=None, default_config=None, no_default_config_action='raise')","text":"Parse the arguments for Config.
You may optionally specify a name for default_config, and CHANfiG will read the file under this name.
There are three levels of config:
Config parsed into this method,default_config (if specified),Higher levels override lower levels (i.e. 3 > 2 > 1).
Parameters:
Name Type Description Defaultargs Iterable[str] | None Command-line arguments. Defaults to None.
None default_config str | None Path to default config file. Defaults to Config.
None no_default_config_action str Action when default_config is not found. Can be one of [\"raise\", \"warn\", \"ignore\"]. Defaults to \"raise\".
'raise' Returns:
Name Type Descriptionconfig Config The parsed Config.
Raises:
Type DescriptionValueError If default_config is specified but not found in args, and no_default_config_action is neither warn nor ignore.
ValueError If no_default_config_action is not in raise, warn and ignore.
parse: Parse all command-line arguments.
Examples:
Note that all examples uses NestedDict instead of Config for avoiding circular import.
Python Console Session>>> p = ConfigParser()\n>>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n{'a': 1}\nYou can only parse argument that is defined in Config. error: unrecognized arguments: \u2013b 1
>>> p = ConfigParser()\n>>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict()\nTraceback (most recent call last):\nSystemExit: 2\nchanfig/parser.py Pythondef parse_config( # pylint: disable=R0912\nself,\nargs: Sequence[str] | None = None,\nconfig: Config | None = None,\ndefault_config: str | None = None,\nno_default_config_action: str = \"raise\",\n) -> Config:\nr\"\"\"\n Parse the arguments for `Config`.\n You may optionally specify a name for `default_config`,\n and CHANfiG will read the file under this name.\n There are three levels of config:\n 1. The base `Config` parsed into this method,\n 2. The base config file located at the path of `default_config` (if specified),\n 3. The config specified in arguments.\n Higher levels override lower levels (i.e. 3 > 2 > 1).\n Args:\n args (Iterable[str] | None, optional): Command-line arguments. Defaults to `None`.\n default_config (str | None, optional): Path to default config file. Defaults to `Config`.\n no_default_config_action (str, optional): Action when `default_config` is not found.\n Can be one of `[\"raise\", \"warn\", \"ignore\"]`. Defaults to `\"raise\"`.\n Returns:\n config: The parsed `Config`.\n Raises:\n ValueError: If `default_config` is specified but not found in args,\n and `no_default_config_action` is neither `warn` nor `ignore`.\n ValueError: If `no_default_config_action` is not in `raise`, `warn` and `ignore`.\n See Also:\n [`parse`][chanfig.ConfigParser.parse]: Parse all command-line arguments.\n Examples:\n Note that all examples uses NestedDict instead of Config for avoiding circular import.\n >>> p = ConfigParser()\n >>> p.parse_config(['--a', '1'], config=NestedDict(a=2)).dict()\n {'a': 1}\n You can only parse argument that is defined in `Config`.\n error: unrecognized arguments: --b 1\n >>> p = ConfigParser()\n >>> p.parse_config(['--b', '1'], config=NestedDict(a=2)).dict() # doctest: +SKIP\n Traceback (most recent call last):\n SystemExit: 2\n \"\"\"\nif args is None:\nargs = sys.argv[1:]\nif config is None:\nraise ValueError(\"config must be specified\")\nself.add_config_arguments(config)\nif no_default_config_action not in (\"warn\", \"ignore\", \"raise\"):\nraise ValueError(\nf\"no_default_config_action must be one of 'warn', 'ignore', 'raise', bug got {no_default_config_action}\"\n)\nparsed = self.parse_args(args)\n# parse the default config file\nif default_config is not None:\nparsed = self.merge_default_config(parsed, default_config, no_default_config_action)\n# parse the command-line arguments\nreturn config.merge(parsed) # type: ignore\n Bases: NestedDict
Registry for components.
Registry provides 3 core functionalities:
To facilitate the usage scenario, registry is designed to be a decorator. You could register a component by simply calling registry.register, and it will be registered with its name. You may also specify the name of the component by calling registry.register(name=\"ComponentName\").
build makes it easy to construct a component from a configuration. build automatically determines the component to construct by the name field in the configuration. So you could either call registry.build(config) or registry.build(**config). Beyond this, build is just a syntax sugar for registry.init(registry.lookup(name), *args, **kwargs).
lookup is used to lookup for a component by its name. By default, lookup internally calls NestedDict.get, but you may override it to provide more functionalities.
init is used to construct a component. By default, init internally calls cls(*args, **kwargs), but you may override it to provide more functionalities.
Registry inherits from NestedDict.
Therefore, Registry comes in a nested structure by nature. You could create a sub-registry by simply calling registry.sub_registry = Registry, and access through registry.sub_registry.register().
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... @registry.register(\"Module1\")\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> module = registry.register(Module, \"Module2\")\n>>> registry\nRegistry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n)\n>>> module = registry.register(Module, \"Module\")\nTraceback (most recent call last):\nValueError: Component with name Module already registered.\n>>> registry.lookup(\"Module\")\n<class 'chanfig.registry.Module'>\n>>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n>>> # registry.register(Module)\n>>> module = registry.build(config[\"module\"])\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\nchanfig/registry.py Pythonclass Registry(NestedDict): # type: ignore\n\"\"\"\n `Registry` for components.\n Registry provides 3 core functionalities:\n - Register a new component.\n - Lookup for a component.\n - Build a component.\n To facilitate the usage scenario, `registry` is designed to be a decorator.\n You could register a component by simply calling `registry.register`, and it will be registered with its name.\n You may also specify the name of the component by calling `registry.register(name=\"ComponentName\")`.\n `build` makes it easy to construct a component from a configuration.\n `build` automatically determines the component to construct by the `name` field in the configuration.\n So you could either call `registry.build(config)` or `registry.build(**config)`.\n Beyond this, `build` is just a syntax sugar for `registry.init(registry.lookup(name), *args, **kwargs)`.\n `lookup` is used to lookup for a component by its name.\n By default, `lookup` internally calls `NestedDict.get`, but you may override it to provide more functionalities.\n `init` is used to construct a component.\n By default, `init` internally calls `cls(*args, **kwargs)`, but you may override it to provide more functionalities.\n Notes:\n `Registry` inherits from `NestedDict`.\n Therefore, `Registry` comes in a nested structure by nature.\n You could create a sub-registry by simply calling `registry.sub_registry = Registry`,\n and access through `registry.sub_registry.register()`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n >>> module = registry.register(Module, \"Module\")\n Traceback (most recent call last):\n ValueError: Component with name Module already registered.\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\noverride: bool = False\ndef __init__(self, override: bool | None = None, fallback: bool | None = None):\nsuper().__init__(fallback=fallback)\nif override is not None:\nself.setattr(\"override\", override)\ndef register(self, component: Any = None, name: Any | None = None) -> Callable:\nr\"\"\"\n Register a new component.\n Args:\n component: The component to register.\n name: The name of the component.\n Returns:\n component: The registered component.\n Registered component are expected to be `Callable`.\n Raises:\n ValueError: If the component with the same name already registered and `Registry.override=False`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n \"\"\"\nif name in self and not self.override:\nraise ValueError(f\"Component with name {name} already registered.\")\n# Registry.register()\nif name is not None:\nself.set(name, component)\nreturn component # type: ignore\n# @Registry.register\nif callable(component) and name is None:\nself.set(component.__name__, component)\nreturn component\n# @Registry.register()\ndef decorator(name: Any | None = None):\n@wraps(self.register)\ndef wrapper(component):\nif name is None:\nself.set(component.__name__, component)\nelse:\nself.set(name, component)\nreturn component\nreturn wrapper\nreturn decorator(component)\ndef lookup(self, name: str) -> Any:\nr\"\"\"\n Lookup for a component.\n Args:\n name:\n Returns:\n (Any): The component.\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n \"\"\"\nreturn self[name]\n@staticmethod\ndef init(cls: Callable, *args: Any, **kwargs: Any) -> Any: # type: ignore # pylint: disable=W0211\nr\"\"\"\n Constructor of component.\n Args:\n cls: The component to construct.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Examples:\n >>> class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> kwargs = {\"a\": 1, \"b\": 2}\n >>> module = Registry.init(Module, **kwargs)\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\nreturn cls(*args, **kwargs)\ndef build(self, name: str | Mapping, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Build a component.\n Args:\n name (str | Mapping):\n If its a `Mapping`, it must contain `\"name\"` as a member, the rest will be treated as `**kwargs`.\n Note that values in `kwargs` will override values in `name` if its a `Mapping`.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(**config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n >>> module = registry.build(config[\"module\"], a=2)\n >>> module.a\n 2\n \"\"\"\nif isinstance(name, Mapping):\nname = deepcopy(name)\nname, kwargs = name.pop(\"name\"), dict(name, **kwargs) # type: ignore\nreturn self.init(self.lookup(name), *args, **kwargs) # type: ignore\nbuild(name, *args, **kwargs)","text":"Build a component.
Parameters:
Name Type Description Defaultname str | Mapping If its a Mapping, it must contain \"name\" as a member, the rest will be treated as **kwargs. Note that values in kwargs will override values in name if its a Mapping.
*args Any The arguments to pass to the component.
() **kwargs Any The keyword arguments to pass to the component.
{} Returns:
Type DescriptionAny Raises:
Type DescriptionKeyError If the component is not registered.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n>>> # registry.register(Module)\n>>> module = registry.build(**config[\"module\"])\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\n>>> module = registry.build(config[\"module\"], a=2)\n>>> module.a\n2\nchanfig/registry.py Pythondef build(self, name: str | Mapping, *args: Any, **kwargs: Any) -> Any:\nr\"\"\"\n Build a component.\n Args:\n name (str | Mapping):\n If its a `Mapping`, it must contain `\"name\"` as a member, the rest will be treated as `**kwargs`.\n Note that values in `kwargs` will override values in `name` if its a `Mapping`.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> config = {\"module\": {\"name\": \"Module\", \"a\": 1, \"b\": 2}}\n >>> # registry.register(Module)\n >>> module = registry.build(**config[\"module\"])\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n >>> module = registry.build(config[\"module\"], a=2)\n >>> module.a\n 2\n \"\"\"\nif isinstance(name, Mapping):\nname = deepcopy(name)\nname, kwargs = name.pop(\"name\"), dict(name, **kwargs) # type: ignore\nreturn self.init(self.lookup(name), *args, **kwargs) # type: ignore\ninit(*args, **kwargs) staticmethod","text":"Constructor of component.
Parameters:
Name Type Description Defaultcls Callable The component to construct.
required*args Any The arguments to pass to the component.
() **kwargs Any The keyword arguments to pass to the component.
{} Returns:
Type DescriptionAny Examples:
Python Console Session>>> class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> kwargs = {\"a\": 1, \"b\": 2}\n>>> module = Registry.init(Module, **kwargs)\n>>> type(module)\n<class 'chanfig.registry.Module'>\n>>> module.a\n1\n>>> module.b\n2\nchanfig/registry.py Python@staticmethod\ndef init(cls: Callable, *args: Any, **kwargs: Any) -> Any: # type: ignore # pylint: disable=W0211\nr\"\"\"\n Constructor of component.\n Args:\n cls: The component to construct.\n *args: The arguments to pass to the component.\n **kwargs: The keyword arguments to pass to the component.\n Returns:\n (Any):\n Examples:\n >>> class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> kwargs = {\"a\": 1, \"b\": 2}\n >>> module = Registry.init(Module, **kwargs)\n >>> type(module)\n <class 'chanfig.registry.Module'>\n >>> module.a\n 1\n >>> module.b\n 2\n \"\"\"\nreturn cls(*args, **kwargs)\nlookup(name)","text":"Lookup for a component.
Parameters:
Name Type Description Defaultname str required Returns:
Type DescriptionAny The component.
Raises:
Type DescriptionKeyError If the component is not registered.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> registry.lookup(\"Module\")\n<class 'chanfig.registry.Module'>\nchanfig/registry.py Pythondef lookup(self, name: str) -> Any:\nr\"\"\"\n Lookup for a component.\n Args:\n name:\n Returns:\n (Any): The component.\n Raises:\n KeyError: If the component is not registered.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> registry.lookup(\"Module\")\n <class 'chanfig.registry.Module'>\n \"\"\"\nreturn self[name]\nregister(component=None, name=None)","text":"Register a new component.
Parameters:
Name Type Description Defaultcomponent Any The component to register.
None name Any | None The name of the component.
None Returns:
Name Type Descriptioncomponent Callable The registered component. Registered component are expected to be Callable.
Raises:
Type DescriptionValueError If the component with the same name already registered and Registry.override=False.
Examples:
Python Console Session>>> registry = Registry()\n>>> @registry.register\n... @registry.register(\"Module1\")\n... class Module:\n... def __init__(self, a, b):\n... self.a = a\n... self.b = b\n>>> module = registry.register(Module, \"Module2\")\n>>> registry\nRegistry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n)\nchanfig/registry.py Pythondef register(self, component: Any = None, name: Any | None = None) -> Callable:\nr\"\"\"\n Register a new component.\n Args:\n component: The component to register.\n name: The name of the component.\n Returns:\n component: The registered component.\n Registered component are expected to be `Callable`.\n Raises:\n ValueError: If the component with the same name already registered and `Registry.override=False`.\n Examples:\n >>> registry = Registry()\n >>> @registry.register\n ... @registry.register(\"Module1\")\n ... class Module:\n ... def __init__(self, a, b):\n ... self.a = a\n ... self.b = b\n >>> module = registry.register(Module, \"Module2\")\n >>> registry\n Registry(\n ('Module1'): <class 'chanfig.registry.Module'>\n ('Module'): <class 'chanfig.registry.Module'>\n ('Module2'): <class 'chanfig.registry.Module'>\n )\n \"\"\"\nif name in self and not self.override:\nraise ValueError(f\"Component with name {name} already registered.\")\n# Registry.register()\nif name is not None:\nself.set(name, component)\nreturn component # type: ignore\n# @Registry.register\nif callable(component) and name is None:\nself.set(component.__name__, component)\nreturn component\n# @Registry.register()\ndef decorator(name: Any | None = None):\n@wraps(self.register)\ndef wrapper(component):\nif name is None:\nself.set(component.__name__, component)\nelse:\nself.set(name, component)\nreturn component\nreturn wrapper\nreturn decorator(component)\n Bases: type
Metaclass for Singleton Classes.
Source code inchanfig/utils.py Pythonclass Singleton(type):\nr\"\"\"\n Metaclass for Singleton Classes.\n \"\"\"\n__instances__: Mapping[type, object] = {}\ndef __call__(cls, *args: Any, **kwargs: Any):\nif cls not in cls.__instances__:\ncls.__instances__[cls] = super().__call__(*args, **kwargs) # type: ignore\nreturn cls.__instances__[cls]\noptions: heading_level: 0
"},{"location":"utils/#chanfigutilsnull","title":"chanfig.utils.Null","text":"Null is an instance of NULL.
Since the metaclass of NULL is Singleton, it is advised to use obj is Null to determine if obj is Null.
NULL class.
get method in CHANfiG may accept None or Ellipse(...) as value of default. Therefore, it is mandatory to have a different default value for default.
Null is an instance of NULL and is recommended to be used as obj is Null.
chanfig/utils.py Pythonclass NULL(metaclass=Singleton):\nr\"\"\"\n NULL class.\n `get` method in CHANfiG may accept `None` or `Ellipse`(`...`) as value of `default`.\n Therefore, it is mandatory to have a different default value for `default`.\n `Null` is an instance of `NULL` and is recommended to be used as `obj is Null`.\n \"\"\"\ndef __repr__(self):\nreturn \"Null\"\ndef __nonzero__(self):\nreturn False\ndef __len__(self):\nreturn 0\ndef __call__(self, *args: Any, **kwargs: Any):\nreturn self\ndef __contains__(self, name):\nreturn False\ndef __iter__(self):\nreturn self\ndef __next__(self):\nraise StopIteration\ndef __getattr__(self, name):\nreturn self\ndef __getitem__(self, index):\nreturn self\noptions: heading_level: 0
Bases: JSONEncoder
JSON encoder for Config.
Source code inchanfig/utils.py Pythonclass JsonEncoder(JSONEncoder):\nr\"\"\"\n JSON encoder for Config.\n \"\"\"\ndef default(self, o: Any) -> Any:\nif hasattr(o, \"__json__\"):\nreturn o.__json__()\nreturn super().default(o)\noptions: heading_level: 0
Bases: SafeDumper
YAML Dumper for Config.
Source code inchanfig/utils.py Pythonclass YamlDumper(SafeDumper): # pylint: disable=R0903\nr\"\"\"\n YAML Dumper for Config.\n \"\"\"\ndef increase_indent(self, flow: bool = False, indentless: bool = False): # pylint: disable=W0235\nreturn super().increase_indent(flow, indentless)\noptions: heading_level: 0
Bases: SafeLoader
YAML Loader for Config.
Source code inchanfig/utils.py Pythonclass YamlLoader(SafeLoader): # pylint: disable=R0901,R0903\nr\"\"\"\n YAML Loader for Config.\n \"\"\"\noptions: heading_level: 0
"},{"location":"variable/","title":"Variable","text":" Bases: Generic[V]
Mutable wrapper for immutable objects.
Parameters:
Name Type Description Defaultvalue Any The value to wrap.
Null type type | None Desired type of the value.
None choices list | None Possible values of the value.
None validator Callable | None Callable that validates the value.
None required bool Whether the value is required.
False help str | None Help message of the value.
None Raises:
Type DescriptionRuntimeError If required is True and value is Null.
TypeError If type is specified and value is not an instance of type.
ValueError | If choices is specified and value is not in choices. If validator is specified and validator returns False.
Attributes:
Name Type Descriptionvalue Any The wrapped value.
dtype type The type of the wrapped value.
NotesVariable by default wrap the instance type to type of the wrapped object. Therefore, isinstance(Variable(1), int) will return True.
To temporarily disable this behaviour, you can call context manager with Variable.unwrapped().
To permanently disable this behaviour, you can call Variable.unwrap().
Examples:
Python Console Session>>> v = Variable(1)\n>>> n = v\n>>> v, n\n(1, 1)\n>>> v += 1\n>>> v, n\n(2, 2)\n>>> v.value = 3\n>>> v, n\n(3, 3)\n>>> n.set(4)\n>>> v, n\n(4, 4)\n>>> n = 5\n>>> v, n\n(4, 5)\n>>> f'{v} < {n}'\n'4 < 5'\n>>> isinstance(v, int)\nTrue\n>>> type(v)\n<class 'chanfig.variable.Variable'>\n>>> v.dtype\n<class 'int'>\n>>> with v.unwrapped():\n... isinstance(v, int)\nFalse\n>>> v = Variable('hello')\n>>> f'{v}, world!'\n'hello, world!'\n>>> v += ', world!'\n>>> v\n'hello, world!'\n>>> \"hello\" in v\nTrue\nchanfig/variable.py Pythonclass Variable(Generic[V]): # pylint: disable=R0902\nr\"\"\"\n Mutable wrapper for immutable objects.\n Args:\n value: The value to wrap.\n type: Desired type of the value.\n choices: Possible values of the value.\n validator: `Callable` that validates the value.\n required: Whether the value is required.\n help: Help message of the value.\n Raises:\n RuntimeError: If `required` is `True` and `value` is `Null`.\n TypeError: If `type` is specified and `value` is not an instance of `type`.\n ValueError: |\n If `choices` is specified and `value` is not in `choices`.\n If `validator` is specified and `validator` returns `False`.\n Attributes:\n value: The wrapped value.\n dtype: The type of the wrapped value.\n Notes:\n `Variable` by default wrap the instance type to type of the wrapped object.\n Therefore, `isinstance(Variable(1), int)` will return `True`.\n To temporarily disable this behaviour, you can call context manager `with Variable.unwrapped()`.\n To permanently disable this behaviour, you can call `Variable.unwrap()`.\n Examples:\n >>> v = Variable(1)\n >>> n = v\n >>> v, n\n (1, 1)\n >>> v += 1\n >>> v, n\n (2, 2)\n >>> v.value = 3\n >>> v, n\n (3, 3)\n >>> n.set(4)\n >>> v, n\n (4, 4)\n >>> n = 5\n >>> v, n\n (4, 5)\n >>> f'{v} < {n}'\n '4 < 5'\n >>> isinstance(v, int)\n True\n >>> type(v)\n <class 'chanfig.variable.Variable'>\n >>> v.dtype\n <class 'int'>\n >>> with v.unwrapped():\n ... isinstance(v, int)\n False\n >>> v = Variable('hello')\n >>> f'{v}, world!'\n 'hello, world!'\n >>> v += ', world!'\n >>> v\n 'hello, world!'\n >>> \"hello\" in v\n True\n \"\"\"\nwrap_type: bool = True\n_storage: List[Any]\n_type: Optional[type] = None\n_choices: Optional[list] = None\n_validator: Optional[Callable] = None\n_required: bool = False\n_help: Optional[str] = None\ndef __init__( # pylint: disable=R0913\nself,\nvalue: Any = Null,\ntype: type | None = None, # pylint: disable=W0622\nchoices: list | None = None,\nvalidator: Callable | None = None,\nrequired: bool = False,\nhelp: str | None = None, # pylint: disable=W0622\n) -> None:\nself._storage = [value]\nself._type = type\nself._choices = choices\nself._validator = validator\nself._required = required\nself._help = help\n@property # type: ignore\ndef __class__(self) -> type:\nreturn self.value.__class__ if self.wrap_type else type(self)\n@property\ndef value(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self._storage[0]\n@value.setter\ndef value(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n \"\"\"\nself.validate(value)\nself._storage[0] = self._get_value(value)\n@property\ndef dtype(self) -> type:\nr\"\"\"\n Data type of the object wrapped in `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> type(id)\n <class 'chanfig.variable.Variable'>\n >>> id.dtype\n <class 'int'>\n >>> issubclass(id.dtype, int)\n True\n \"\"\"\nreturn self.value.__class__\n@property\ndef storage(self) -> list[Any]:\nr\"\"\"\n Storage of `Variable`.\n \"\"\"\nreturn self._storage\n@property\ndef type(self) -> type | None:\nreturn self._type\n@property\ndef choices(self) -> list | None:\nreturn self._choices\n@property\ndef validator(self) -> Callable | None:\nreturn self._validator\n@property\ndef required(self) -> bool:\nreturn self._required\n@property\ndef help(self) -> str:\nreturn self._help or \"\"\ndef validate(self, *args) -> None:\nr\"\"\"\n Validate if the value is valid.\n \"\"\"\nif len(args) == 0:\nvalue = self.value\nelif len(args) == 1:\nvalue = args[0]\nelse:\nraise ValueError(\"Too many arguments.\")\nif self._required and value is Null:\nraise RuntimeError(\"Value is required.\")\nif self._type is not None and not isinstance(value, self._type):\nraise TypeError(f\"Value {value} is not of type {self._type}.\")\nif self._choices is not None and value not in self._choices:\nraise ValueError(f\"Value {value} is not in choices {self._choices}.\")\nif self._validator is not None and not self._validator(value):\nraise ValueError(f\"Value {value} is not valid.\")\ndef get(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self.value\ndef set(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n `Variable.set` is extremely useful when you want to change the value without changing the reference.\n In `FlatDict.set`, all assignments of `Variable` calls `Variable.set` Internally.\n \"\"\"\nself.value = value\ndef __get__(self, obj, objtype=None):\nreturn self\ndef __set__(self, obj, value):\nself.value = value\ndef to(self, cls: Callable) -> Any: # pylint: disable=C0103\nr\"\"\"\n Convert the object wrapped in `Variable` to target `cls`.\n Args:\n cls: The type to convert to.\n Examples:\n >>> id = Variable(1013)\n >>> id.to(float)\n 1013.0\n >>> id.to(str)\n '1013.0'\n \"\"\"\nself.value = cls(self.value)\nreturn self\ndef int(self) -> int:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `int`.\n Examples:\n >>> id = Variable(1013.0)\n >>> id.int()\n 1013\n \"\"\"\nreturn self.to(int)\ndef float(self) -> float:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.float()\n 1013.0\n \"\"\"\nreturn self.to(float)\ndef str(self) -> str:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.str()\n '1013'\n \"\"\"\nreturn self.to(str)\ndef wrap(self) -> None:\nr\"\"\"\n Wrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n >>> id.wrap()\n >>> isinstance(id, int)\n True\n \"\"\"\nself.wrap_type = True\ndef unwrap(self) -> None:\nr\"\"\"\n Unwrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n \"\"\"\nself.wrap_type = False\n@contextmanager\ndef unwrapped(self):\nr\"\"\"\n Context manager which temporarily unwrap the `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> isinstance(id, int)\n True\n >>> with id.unwrapped():\n ... isinstance(id, int)\n False\n \"\"\"\nwrap_type = self.wrap_type\nself.wrap_type = False\ntry:\nyield self\nfinally:\nself.wrap_type = wrap_type\n@staticmethod\ndef _get_value(obj) -> Any:\nif isinstance(obj, Variable):\nreturn obj.value\nreturn obj\ndef __getattr__(self, attr) -> Any:\nreturn getattr(self.value, attr)\ndef __lt__(self, other) -> bool:\nreturn self.value < self._get_value(other)\ndef __le__(self, other) -> bool:\nreturn self.value <= self._get_value(other)\ndef __eq__(self, other) -> bool:\nreturn self.value == self._get_value(other)\ndef __ne__(self, other) -> bool:\nreturn self.value != self._get_value(other)\ndef __ge__(self, other) -> bool:\nreturn self.value >= self._get_value(other)\ndef __gt__(self, other) -> bool:\nreturn self.value > self._get_value(other)\ndef __index__(self):\nreturn self.value.__index__()\ndef __invert__(self):\nreturn ~self.value\ndef __abs__(self):\nreturn abs(self.value)\ndef __add__(self, other):\nreturn Variable(self.value + self._get_value(other))\ndef __radd__(self, other):\nreturn Variable(self._get_value(other) + self.value)\ndef __iadd__(self, other):\nself.value += self._get_value(other)\nreturn self\ndef __and__(self, other):\nreturn Variable(self.value & self._get_value(other))\ndef __rand__(self, other):\nreturn Variable(self._get_value(other) & self.value)\ndef __iand__(self, other):\nself.value &= self._get_value(other)\nreturn self\ndef __floordiv__(self, other):\nreturn Variable(self.value // self._get_value(other))\ndef __rfloordiv__(self, other):\nreturn Variable(self._get_value(other) // self.value)\ndef __ifloordiv__(self, other):\nself.value //= self._get_value(other)\nreturn self\ndef __mod__(self, other):\nreturn Variable(self.value % self._get_value(other))\ndef __rmod__(self, other):\nreturn Variable(self._get_value(other) % self.value)\ndef __imod__(self, other):\nself.value %= self._get_value(other)\nreturn self\ndef __mul__(self, other):\nreturn Variable(self.value * self._get_value(other))\ndef __rmul__(self, other):\nreturn Variable(self._get_value(other) * self.value)\ndef __imul__(self, other):\nself.value *= self._get_value(other)\nreturn self\ndef __matmul__(self, other):\nreturn Variable(self.value @ self._get_value(other))\ndef __rmatmul__(self, other):\nreturn Variable(self._get_value(other) @ self.value)\ndef __imatmul__(self, other):\nself.value @= self._get_value(other)\nreturn self\ndef __pow__(self, other):\nreturn Variable(self.value ** self._get_value(other))\ndef __rpow__(self, other):\nreturn Variable(self._get_value(other) ** self.value)\ndef __ipow__(self, other):\nself.value **= self._get_value(other)\nreturn self\ndef __truediv__(self, other):\nreturn Variable(self.value / self._get_value(other))\ndef __rtruediv__(self, other):\nreturn Variable(self._get_value(other) / self.value)\ndef __itruediv__(self, other):\nself.value /= self._get_value(other)\nreturn self\ndef __sub__(self, other):\nreturn Variable(self.value - self._get_value(other))\ndef __rsub__(self, other):\nreturn Variable(self._get_value(other) - self.value)\ndef __isub__(self, other):\nself.value -= self._get_value(other)\nreturn self\ndef __copy__(self):\nreturn Variable(self.value)\ndef __deepcopy__(self, memo: Mapping | None = None):\nreturn Variable(copy(self.value))\ndef __format__(self, format_spec):\nreturn self.value if isinstance(self, str) else format(self.value, format_spec)\ndef __iter__(self):\nreturn iter(self.value)\ndef __next__(self):\nreturn next(self.value)\ndef __hash__(self):\nreturn hash(self.value)\ndef __repr__(self):\nreturn repr(self.value)\ndef __str__(self):\nreturn self.value if isinstance(self, str) else str(self.value)\ndef __json__(self):\nreturn self.value\ndef __contains__(self, name):\nreturn name in self.value\ndtype: type property","text":"Data type of the object wrapped in Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> type(id)\n<class 'chanfig.variable.Variable'>\n>>> id.dtype\n<class 'int'>\n>>> issubclass(id.dtype, int)\nTrue\nstorage: list[Any] property","text":"Storage of Variable.
value: Any property writable","text":"Fetch the object wrapped in Variable.
float()","text":"Convert the object wrapped in Variable to python float.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.float()\n1013.0\nchanfig/variable.py Pythondef float(self) -> float:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.float()\n 1013.0\n \"\"\"\nreturn self.to(float)\nget()","text":"Fetch the object wrapped in Variable.
chanfig/variable.py Pythondef get(self) -> Any:\nr\"\"\"\n Fetch the object wrapped in `Variable`.\n \"\"\"\nreturn self.value\nint()","text":"Convert the object wrapped in Variable to python int.
Examples:
Python Console Session>>> id = Variable(1013.0)\n>>> id.int()\n1013\nchanfig/variable.py Pythondef int(self) -> int:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `int`.\n Examples:\n >>> id = Variable(1013.0)\n >>> id.int()\n 1013\n \"\"\"\nreturn self.to(int)\nset(value)","text":"Assign value to the object wrapped in Variable.
Variable.set is extremely useful when you want to change the value without changing the reference.
In FlatDict.set, all assignments of Variable calls Variable.set Internally.
chanfig/variable.py Pythondef set(self, value) -> None:\nr\"\"\"\n Assign value to the object wrapped in `Variable`.\n `Variable.set` is extremely useful when you want to change the value without changing the reference.\n In `FlatDict.set`, all assignments of `Variable` calls `Variable.set` Internally.\n \"\"\"\nself.value = value\nstr()","text":"Convert the object wrapped in Variable to python float.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.str()\n'1013'\nchanfig/variable.py Pythondef str(self) -> str:\nr\"\"\"\n Convert the object wrapped in `Variable` to python `float`.\n Examples:\n >>> id = Variable(1013)\n >>> id.str()\n '1013'\n \"\"\"\nreturn self.to(str)\nto(cls)","text":"Convert the object wrapped in Variable to target cls.
Parameters:
Name Type Description Defaultcls Callable The type to convert to.
requiredExamples:
Python Console Session>>> id = Variable(1013)\n>>> id.to(float)\n1013.0\n>>> id.to(str)\n'1013.0'\nchanfig/variable.py Pythondef to(self, cls: Callable) -> Any: # pylint: disable=C0103\nr\"\"\"\n Convert the object wrapped in `Variable` to target `cls`.\n Args:\n cls: The type to convert to.\n Examples:\n >>> id = Variable(1013)\n >>> id.to(float)\n 1013.0\n >>> id.to(str)\n '1013.0'\n \"\"\"\nself.value = cls(self.value)\nreturn self\nunwrap()","text":"Unwrap the type of Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.unwrap()\n>>> isinstance(id, int)\nFalse\nchanfig/variable.py Pythondef unwrap(self) -> None:\nr\"\"\"\n Unwrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n \"\"\"\nself.wrap_type = False\nunwrapped()","text":"Context manager which temporarily unwrap the Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> isinstance(id, int)\nTrue\n>>> with id.unwrapped():\n... isinstance(id, int)\nFalse\nchanfig/variable.py Python@contextmanager\ndef unwrapped(self):\nr\"\"\"\n Context manager which temporarily unwrap the `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> isinstance(id, int)\n True\n >>> with id.unwrapped():\n ... isinstance(id, int)\n False\n \"\"\"\nwrap_type = self.wrap_type\nself.wrap_type = False\ntry:\nyield self\nfinally:\nself.wrap_type = wrap_type\nvalidate(*args)","text":"Validate if the value is valid.
Source code inchanfig/variable.py Pythondef validate(self, *args) -> None:\nr\"\"\"\n Validate if the value is valid.\n \"\"\"\nif len(args) == 0:\nvalue = self.value\nelif len(args) == 1:\nvalue = args[0]\nelse:\nraise ValueError(\"Too many arguments.\")\nif self._required and value is Null:\nraise RuntimeError(\"Value is required.\")\nif self._type is not None and not isinstance(value, self._type):\nraise TypeError(f\"Value {value} is not of type {self._type}.\")\nif self._choices is not None and value not in self._choices:\nraise ValueError(f\"Value {value} is not in choices {self._choices}.\")\nif self._validator is not None and not self._validator(value):\nraise ValueError(f\"Value {value} is not valid.\")\nwrap()","text":"Wrap the type of Variable.
Examples:
Python Console Session>>> id = Variable(1013)\n>>> id.unwrap()\n>>> isinstance(id, int)\nFalse\n>>> id.wrap()\n>>> isinstance(id, int)\nTrue\nchanfig/variable.py Pythondef wrap(self) -> None:\nr\"\"\"\n Wrap the type of `Variable`.\n Examples:\n >>> id = Variable(1013)\n >>> id.unwrap()\n >>> isinstance(id, int)\n False\n >>> id.wrap()\n >>> isinstance(id, int)\n True\n \"\"\"\nself.wrap_type = True\nCHANfiG \u200b\u5e0c\u671b\u200b\u80fd\u200b\u8ba9\u200b\u4f60\u200b\u7684\u200b\u914d\u7f6e\u200b\u66f4\u52a0\u200b\u7b80\u5355\u200b\u3002
\u200b\u8bad\u7ec3\u200b\u4e00\u4e2a\u200b\u673a\u5668\u200b\u5b66\u4e60\u200b\u6a21\u578b\u200b\u6709\u200b\u65e0\u6570\u4e2a\u200b\u53ef\u200b\u8c03\u8282\u200b\u7684\u200b\u53c2\u6570\u200b\u3002 \u200b\u4e3a\u4e86\u200b\u8c03\u8282\u200b\u6240\u6709\u200b\u53c2\u6570\u200b\uff0c\u200b\u7814\u7a76\u5458\u200b\u4eec\u200b\u5e38\u5e38\u200b\u9700\u8981\u200b\u64b0\u5199\u200b\u5de8\u5927\u200b\u7684\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u6709\u65f6\u200b\u751a\u81f3\u200b\u957f\u200b\u8fbe\u200b\u6570\u5343\u200b\u884c\u200b\u3002 \u200b\u5927\u591a\u6570\u200b\u53c2\u6570\u200b\u53ea\u662f\u200b\u65b9\u6cd5\u200b\u9ed8\u8ba4\u200b\u53c2\u6570\u200b\u7684\u200b\u7b80\u5355\u200b\u91cd\u590d\u200b\uff0c\u200b\u8fd9\u200b\u5bfc\u81f4\u200b\u4e86\u200b\u5f88\u591a\u200b\u4e0d\u5fc5\u8981\u200b\u7684\u200b\u58f0\u660e\u200b\u3002 \u200b\u6b64\u5916\u200b\uff0c\u200b\u8c03\u8282\u200b\u8fd9\u4e9b\u200b\u53c2\u6570\u200b\u540c\u6837\u200b\u5f88\u200b\u7e41\u7410\u200b\uff0c\u200b\u9700\u8981\u200b\u5b9a\u4f4d\u200b\u5e76\u200b\u6253\u5f00\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u4f5c\u51fa\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u4fdd\u5b58\u200b\u5173\u95ed\u200b\u3002 \u200b\u8fd9\u4e2a\u200b\u8fc7\u7a0b\u200b\u6d6a\u8d39\u200b\u4e86\u200b\u65e0\u6570\u200b\u7684\u200b\u5b9d\u8d35\u65f6\u95f4\u200b \u200b\u8fd9\u200b\u65e0\u7591\u200b\u662f\u200b\u4e00\u79cd\u200b\u72af\u7f6a\u200b \u3002 \u200b\u4f7f\u7528\u200bargparse\u200b\u53ef\u4ee5\u200b\u5728\u200b\u4e00\u5b9a\u200b\u7a0b\u5ea6\u200b\u4e0a\u200b\u7f13\u89e3\u200b\u8c03\u53c2\u200b\u7684\u200b\u4e0d\u53d8\u200b\uff0c\u200b\u4f46\u662f\u200b\uff0c\u200b\u8981\u200b\u8ba9\u200b\u4ed6\u200b\u548c\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u9002\u914d\u200b\u4f9d\u7136\u200b\u9700\u8981\u200b\u5f88\u591a\u200b\u5de5\u4f5c\u200b\uff0c\u200b\u5e76\u4e14\u200b\u7f3a\u4e4f\u200b\u5d4c\u5957\u200b\u4e5f\u200b\u9650\u5236\u200b\u4e86\u200b\u4ed6\u200b\u7684\u200b\u6f5c\u529b\u200b\u3002
CHANfiG \u200b\u65e8\u5728\u200b\u5e26\u6765\u200b\u6539\u53d8\u200b\u3002
\u200b\u4f60\u200b\u53ea\u200b\u9700\u8981\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u8f93\u5165\u200b\u4f60\u200b\u7684\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u628a\u200b\u5269\u4e0b\u200b\u7684\u200b\u4ea4\u7ed9\u200b CHANfiG\u3002
CHANfiG \u200b\u5f88\u5927\u200b\u7a0b\u5ea6\u200b\u4e0a\u200b\u542f\u53d1\u200b\u81ea\u200bYACS\u3002 \u200b\u4e0d\u540c\u4e8e\u200b YACS \u200b\u7684\u200b\u8303\u5f0f\u200b\uff08\u200b\u4ee3\u7801\u200b + \u200b\u5b9e\u9a8c\u200bE\u200b\u7684\u200bYACS\u200b\u914d\u7f6e\u6587\u4ef6\u200b (+ \u200b\u5916\u90e8\u200b\u4f9d\u8d56\u200b + \u200b\u786c\u4ef6\u200b + \u200b\u5176\u4ed6\u200b\u4ee4\u4eba\u8ba8\u538c\u200b\u7684\u200b\u672f\u8bed\u200b ...) = \u200b\u53ef\u200b\u91cd\u590d\u200b\u7684\u200b\u5b9e\u9a8c\u200bE\uff09\uff0c CHANfiG \u200b\u7684\u200b\u8303\u5f0f\u200b\u662f\u200b\uff1a
\u200b\u4ee3\u7801\u200b + \u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b (+ \u200b\u53ef\u9009\u200b\u7684\u200bCHANfiG\u200b\u914d\u7f6e\u6587\u4ef6\u200b + \u200b\u5916\u90e8\u200b\u4f9d\u8d56\u200b + \u200b\u786c\u4ef6\u200b + \u200b\u5176\u4ed6\u200b\u4ee4\u4eba\u8ba8\u538c\u200b\u7684\u200b\u672f\u8bed\u200b ...) = \u200b\u53ef\u200b\u91cd\u590d\u200b\u7684\u200b\u5b9e\u9a8c\u200bE (+ \u200b\u53ef\u9009\u200b\u7684\u200bCHANfiG\u200b\u914d\u7f6e\u6587\u4ef6\u200b)
\u200b\u4e00\u4e2a\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u53ef\u4ee5\u200b\u88ab\u200b\u770b\u4f5c\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7684\u200b\u5b57\u5178\u200b\u7ed3\u6784\u200b\u3002
\u200b\u4f46\u662f\u200b\uff0c\u200b\u9ed8\u8ba4\u200b\u7684\u200b Python \u200b\u5b57\u5178\u200b\u5341\u5206\u200b\u96be\u4ee5\u200b\u64cd\u4f5c\u200b\u3002
\u200b\u8bbf\u95ee\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u7684\u200b\u552f\u4e00\u200b\u65b9\u5f0f\u200b\u662f\u200bdict['name']\uff0c\u200b\u8fd9\u200b\u65e0\u7591\u200b\u662f\u200b\u6781\u5176\u200b\u7e41\u7410\u200b\u7684\u200b\u3002 \u200b\u66f4\u200b\u7cdf\u7cd5\u200b\u7684\u200b\uff0c\u200b\u5982\u679c\u200b\u8fd9\u4e2a\u200b\u5b57\u5178\u200b\u548c\u200b\u914d\u7f6e\u200b\u4e00\u6837\u200b\u662f\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\uff0c\u200b\u8bbf\u95ee\u200b\u6210\u5458\u200b\u5c06\u4f1a\u200b\u53d8\u6210\u200b\u7c7b\u4f3c\u200b\u4e8e\u200bdict['parent']['children']['name']\u200b\u7684\u200b\u6837\u5b50\u200b\u3002
\u200b\u591f\u200b\u4e86\u200b\u5c31\u662f\u200b\u591f\u200b\u4e86\u200b\uff0c\u200b\u662f\u200b\u65f6\u5019\u200b\u505a\u51fa\u200b\u6539\u53d8\u200b\u4e86\u200b\u3002
\u200b\u6211\u4eec\u200b\u9700\u8981\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u7684\u200b\u8bbf\u95ee\u200b\uff0c\u200b\u5e76\u4e14\u200b\u6211\u4eec\u200b\u73b0\u5728\u200b\u5c31\u200b\u9700\u8981\u200b\u3002 dict.name\u200b\u548c\u200bdict.parent.children.name\u200b\u662f\u200b\u6240\u6709\u200b\u4f60\u200b\u9700\u8981\u200b\u7684\u200b\u3002
\u200b\u5c3d\u7ba1\u200b\u6b64\u524d\u200b\u5df2\u7ecf\u200b\u6709\u200b\u5de5\u4f5c\u200b\u6765\u200b\u5b9e\u73b0\u200b\u7c7b\u4f3c\u200b\u7684\u200b\u5bf9\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u7684\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u3002\u200b\u4f46\u662f\u200b\u4ed6\u4eec\u200b\u7684\u200b Config \u200b\u5bf9\u8c61\u200b\u8981\u4e48\u200b\u4f7f\u7528\u200b\u4e00\u4e2a\u200b\u72ec\u7acb\u200b\u7684\u200b\u5b57\u5178\u200b\u6765\u200b\u5b58\u50a8\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u7684\u200b\u4fe1\u606f\u200b\uff08EasyDict\uff09\uff0c\u200b\u800c\u200b\u8fd9\u200b\u53ef\u80fd\u200b\u5bfc\u81f4\u200b\u5c5e\u6027\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u548c\u200b\u5b57\u5178\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u7684\u200b\u4e0d\u200b\u4e00\u81f4\u200b\uff1b\u200b\u8981\u4e48\u200b\u91cd\u65b0\u200b\u4f7f\u7528\u200b\u65e2\u6709\u200b\u7684\u200b__dict__\u200b\u7136\u540e\u200b\u5bf9\u200b\u5b57\u5178\u200b\u65b9\u5f0f\u200b\u8bbf\u95ee\u200b\u8fdb\u884c\u200b\u91cd\u5b9a\u5411\u200b\uff08ml_collections\uff09\uff0c\u200b\u800c\u200b\u8fd9\u200b\u53ef\u80fd\u200b\u5bfc\u81f4\u200b\u5c5e\u6027\u200b\u548c\u200b\u5b57\u5178\u200b\u6210\u5458\u200b\u5b58\u5728\u200b\u51b2\u7a81\u200b\u3002
\u200b\u4e3a\u4e86\u200b\u89e3\u51b3\u200b\u4e0a\u8ff0\u200b\u9650\u5236\u200b\uff0c\u200b\u6211\u4eec\u200b\u7ee7\u627f\u200b\u4e86\u200b Python \u200b\u5185\u7f6e\u200b\u7684\u200bdict\u200b\u6765\u200b\u521b\u5efa\u200bFlatDict\u3001DefaultDict\u3001NestedDict\u3001Config\u200b\u548c\u200bRegistry\u3002 \u200b\u6211\u4eec\u200b\u540c\u65f6\u200b\u4ecb\u7ecd\u200b\u4e86\u200bVariable\u200b\u6765\u200b\u5728\u200b\u591a\u4e2a\u200b\u4f4d\u7f6e\u200b\u5171\u4eab\u200b\u503c\u200b\uff0c\u200b\u548c\u200bConfigParser\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b\u3002
FlatDict\u200b\u5728\u200b\u4e09\u4e2a\u200b\u65b9\u9762\u200b\u5bf9\u200b\u9ed8\u8ba4\u200b\u7684\u200bdict\u200b\u505a\u51fa\u200b\u6539\u8fdb\u200b\u3002
FlatDict\u200b\u652f\u6301\u200b\u53d8\u91cf\u200b\u63d2\u503c\u200b\u3002 \u200b\u5c06\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u8bbe\u7f6e\u200b\u4e3a\u200b${}\u200b\u5305\u88f9\u200b\u7684\u200b\u53e6\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u540d\u200b\uff0c\u200b\u7136\u540e\u200b\u8c03\u7528\u200binterpolate\u200b\u65b9\u6cd5\u200b\u3002 \u200b\u8fd9\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u5c06\u200b\u4f1a\u200b\u81ea\u52a8\u200b\u66ff\u6362\u200b\u4e3a\u200b\u53e6\u200b\u4e00\u4e2a\u200b\u6210\u5458\u200b\u7684\u200b\u503c\u200b\u3002
Python \u200b\u7684\u200bdict\u200b\u81ea\u200b Python 3.7 \u200b\u4e4b\u540e\u200b\u5c31\u662f\u200b\u6709\u5e8f\u200b\u7684\u200b\uff0c\u200b\u4f46\u662f\u200b\u5e76\u200b\u6ca1\u6709\u200b\u4e00\u4e2a\u200b\u5185\u7f6e\u200b\u7684\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u5bf9\u200b\u4e00\u4e2a\u200bdict\u200b\u8fdb\u884c\u200b\u6392\u5e8f\u200b\u3002FlatDict\u200b\u652f\u6301\u200bsort\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u7ba1\u7406\u200b\u4f60\u200b\u7684\u200b\u5b57\u5178\u200b\u3002
FlatDict\u200b\u5305\u62ec\u200b\u4e86\u200b\u4e00\u4e2a\u200bmerge\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u4ed6\u200b\u4f7f\u200b\u4f60\u200b\u80fd\u200b\u5c06\u200b\u4e00\u4e2a\u200bMapping\u3001Iterable\u200b\u6216\u8005\u200b\u4e00\u4e2a\u200b\u8def\u5f84\u200b\u5408\u5e76\u200b\u8fdb\u5165\u200b\u4e00\u4e2a\u200bFlatDict\u3002 \u200b\u4e0e\u200bupdate\u200b\u65b9\u6cd5\u200b\u4e0d\u540c\u200b\uff0cmerge\u200b\u65b9\u6cd5\u200b\u662f\u200b\u8d4b\u503c\u200b\u800c\u200b\u4e0d\u662f\u200b\u66ff\u6362\u200b\uff0c\u200b\u8fd9\u200b\u4f7f\u5f97\u200b\u4ed6\u200b\u80fd\u200b\u66f4\u597d\u200b\u7684\u200b\u4e0e\u200bDefaultDict\u200b\u914d\u5408\u200b\u4f7f\u7528\u200b\u3002
\u200b\u6b64\u5916\u200b\uff0cFlatDict\u200b\u5f15\u5165\u200b\u4e86\u200bdifference\u200b\u548c\u200bintersect\uff0c\u200b\u8fd9\u4e9b\u200b\u4f7f\u200b\u5176\u200b\u53ef\u4ee5\u200b\u975e\u5e38\u7b80\u5355\u200b\u7684\u200b\u5c06\u200bFlatDict\u200b\u548c\u200b\u5176\u4ed6\u200bMapping\u3001Iterable\u200b\u6216\u8005\u200b\u4e00\u4e2a\u200b\u8def\u5f84\u200b\u8fdb\u884c\u200b\u5bf9\u6bd4\u200b\u3002
FlatDict\u200b\u652f\u6301\u200b\u4e0e\u200b Pytorch Tensor \u200b\u7c7b\u4f3c\u200b\u7684\u200bto\u200b\u65b9\u6cd5\u200b\u3002 \u200b\u4f60\u200b\u53ef\u4ee5\u200b\u5f88\u200b\u7b80\u5355\u200b\u7684\u200b\u901a\u8fc7\u200b\u76f8\u540c\u200b\u7684\u200b\u65b9\u5f0f\u200b\u5c06\u200b\u6240\u6709\u200bFlatDict\u200b\u7684\u200b\u6210\u5458\u200b\u503c\u200b\u8f6c\u6362\u200b\u4e3a\u200b\u67d0\u79cd\u200b\u7c7b\u578b\u200b\u6216\u8005\u200b\u8f6c\u79fb\u200b\u5230\u200b\u67d0\u4e2a\u200b\u8bbe\u5907\u200b\u4e0a\u200b\u3002
FlatDict\u200b\u540c\u65f6\u200b\u96c6\u6210\u200b\u4e86\u200bcpu\u3001gpu (cuda)\u3001tpu (xla)\u200b\u65b9\u6cd5\u200b\u6765\u200b\u63d0\u4f9b\u200b\u66f4\u200b\u4fbf\u6377\u200b\u7684\u200b\u8bbf\u95ee\u200b\u3002
FlatDict\u200b\u652f\u6301\u200bjson\u3001jsons\u3001yaml\u200b\u548c\u200byamls\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5c06\u200bFlatDict\u200b\u5b58\u50a8\u200b\u5230\u200b\u6587\u4ef6\u200b\u6216\u8005\u200b\u8f6c\u6362\u6210\u200b\u5b57\u7b26\u4e32\u200b\u3002 \u200b\u5b83\u200b\u8fd8\u200b\u63d0\u4f9b\u200b\u4e86\u200bfrom_json\u3001from_jsons\u3001from_yaml\u200b\u548c\u200bfrom_yamls\u200b\u6765\u200b\u4ece\u200b\u4e00\u4e2a\u200b\u5b57\u7b26\u4e32\u200b\u6216\u8005\u200b\u6587\u4ef6\u200b\u4e2d\u200b\u6784\u5efa\u200bFlatDict\u3002
FlatDict\u200b\u4e5f\u200b\u5305\u62ec\u200b\u4e86\u200bdump\u200b\u548c\u200bload\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u4ed6\u4eec\u200b\u53ef\u4ee5\u200b\u4ece\u6587\u4ef6\u200b\u6269\u5c55\u540d\u200b\u4e2d\u200b\u81ea\u52a8\u200b\u63a8\u65ad\u200b\u7c7b\u578b\u200b\u7136\u540e\u200b\u5c06\u200bFlatDict\u200b\u5b58\u50a8\u200b\u5230\u200b\u6587\u4ef6\u200b\u4e2d\u200b/\u200b\u4ece\u6587\u4ef6\u200b\u4e2d\u200b\u52a0\u8f7d\u200bFlatDict\u3002
\u200b\u4e3a\u4e86\u200b\u6ee1\u8db3\u200b\u9ed8\u8ba4\u503c\u200b\u7684\u200b\u9700\u8981\u200b\uff0c\u200b\u6211\u4eec\u200b\u5305\u62ec\u200b\u4e86\u200b\u4e00\u4e2a\u200bDefaultDict\uff0c\u200b\u4ed6\u200b\u63a5\u53d7\u200bdefault_factory\u200b\u53c2\u6570\u200b\uff0c\u200b\u5e76\u200b\u548c\u200bcollections.defaultdict\u200b\u4e00\u6837\u200b\u5de5\u4f5c\u200b\u3002
\u200b\u7531\u4e8e\u200b\u5927\u591a\u6570\u200b\u914d\u7f6e\u200b\u90fd\u200b\u662f\u200b\u4e00\u4e2a\u200b\u5d4c\u5957\u200b\u7684\u200b\u7ed3\u6784\u200b\uff0c\u200b\u6211\u4eec\u200b\u8fdb\u4e00\u6b65\u200b\u63d0\u51fa\u200b\u4e86\u200bNestedDict\u3002
\u200b\u57fa\u4e8e\u200bDefaultDict\uff0cNestedDict\u200b\u63d0\u4f9b\u200b\u4e86\u200ball_keys\u3001all_values\u3001all_items\u200b\u65b9\u6cd5\u200b\u6765\u200b\u5141\u8bb8\u200b\u4e00\u6b21\u6027\u200b\u904d\u5386\u200b\u6574\u4e2a\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\u3002
NestedDict\u200b\u540c\u65f6\u200b\u63d0\u4f9b\u200b\u4e86\u200bapply\u200b\u548c\u200bapply_\u200b\u65b9\u6cd5\u200b\uff0c\u200b\u5b83\u200b\u53ef\u4ee5\u200b\u4f7f\u200b\u64cd\u7eb5\u200b\u5d4c\u5957\u200b\u7ed3\u6784\u200b\u66f4\u52a0\u200b\u5bb9\u6613\u200b\u3002
Config\u200b\u901a\u8fc7\u200b\u4e24\u4e2a\u200b\u65b9\u9762\u200b\u6765\u200b\u8fdb\u4e00\u6b65\u200b\u63d0\u5347\u200b\u529f\u80fd\u6027\u200b\uff1a \u200b\u652f\u6301\u200bfreeze\u200b\u6765\u200b\u51bb\u7ed3\u200b\u548c\u200bdefrost\u200b\u89e3\u51bb\u200b\u5b57\u5178\u200b\u548c\u200b \u200b\u52a0\u5165\u200b\u5185\u7f6e\u200b\u7684\u200bConfigParser\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u8bed\u53e5\u200b\u3002
\u200b\u6ce8\u610f\u200bConfig\u200b\u9ed8\u8ba4\u8bbe\u7f6e\u200bdefault_factory=Config()\u200b\u6765\u200b\u63d0\u4f9b\u200b\u4fbf\u5229\u200b\u3002
Registry\u200b\u7ee7\u627f\u200b\u81ea\u200bNestedDict\uff0c\u200b\u5e76\u4e14\u200b\u63d0\u4f9b\u200bregister\u3001lookup\u200b\u548c\u200bbuild\u200b\u6765\u200b\u5e2e\u52a9\u200b\u4f60\u200b\u6ce8\u518c\u200b\u6784\u9020\u51fd\u6570\u200b\u5e76\u200b\u4ece\u200bConfig\u200b\u6765\u200b\u521b\u5efa\u5bf9\u8c61\u200b\u3002
\u200b\u6709\u200b\u4e00\u4e2a\u200b\u503c\u200b\u5728\u200b\u591a\u4e2a\u200b\u5730\u65b9\u200b\u4ee5\u200b\u591a\u4e2a\u200b\u540d\u5b57\u200b\u51fa\u73b0\u200b\uff1f\u200b\u6211\u4eec\u200b\u7ed9\u200b\u4f60\u200b\u63d0\u4f9b\u200b\u63a9\u62a4\u200b\u3002
\u200b\u53ea\u8981\u200b\u5c06\u503c\u200b\u4ee5\u200bVariable\u200b\u5305\u88c5\u200b\uff0c\u200b\u7136\u540e\u200b\u6bcf\u5904\u200b\u66f4\u6539\u200b\u90fd\u200b\u4f1a\u200b\u5728\u200b\u5904\u5904\u200b\u4f53\u73b0\u200b\u3002
Variable\u200b\u540c\u65f6\u200b\u652f\u6301\u200btype\u3001choices\u3001validator\u3001required\u200b\u6765\u200b\u786e\u4fdd\u200b\u503c\u200b\u7684\u200b\u6b63\u786e\u6027\u200b\u3002
\u200b\u4e3a\u4e86\u200b\u66f4\u52a0\u200b\u7b80\u5355\u200b\uff0cVariable\u200b\u8fd8\u200b\u652f\u6301\u200bhelp\u200b\u6765\u200b\u5728\u200b\u4f7f\u7528\u200bConfigParser\u200b\u65f6\u200b\u63d0\u4f9b\u200b\u63cf\u8ff0\u200b\u3002
ConfigParser\u200b\u5728\u200bArgumentParser\u200b\u7684\u200b\u57fa\u7840\u200b\u4e4b\u4e0a\u200b\uff0c\u200b\u63d0\u4f9b\u200b\u4e86\u200bparse\u200b\u548c\u200bparse_config\u200b\u6765\u200b\u89e3\u6790\u200b\u547d\u4ee4\u884c\u200b\u53c2\u6570\u200b\u5e76\u200b\u521b\u5efa\u200b/\u200b\u66f4\u65b0\u200bConfig\u3002
CHANfiG \u200b\u6709\u7740\u200b\u5f3a\u5927\u200b\u7684\u200b\u524d\u200b\u5411\u200b\u517c\u5bb9\u200b\u80fd\u529b\u200b\uff0c\u200b\u80fd\u591f\u200b\u826f\u597d\u200b\u7684\u200b\u517c\u5bb9\u200b\u4ee5\u5f80\u200b\u57fa\u4e8e\u200b yaml \u200b\u548c\u200b json \u200b\u7684\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u3002
\u200b\u5982\u679c\u200b\u4f60\u200b\u6b64\u524d\u200b\u4f7f\u7528\u200b yacs\uff0c\u200b\u53ea\u200b\u9700\u200b\u7b80\u5355\u200b\u5c06\u200bCfgNode\u200b\u66ff\u6362\u200b\u4e3a\u200bConfig\u200b\u4fbf\u200b\u53ef\u4ee5\u200b\u4eab\u53d7\u200b\u6240\u6709\u200b CHANfiG \u200b\u6240\u200b\u63d0\u4f9b\u200b\u7684\u200b\u4fbf\u5229\u200b\u3002
\u200b\u66f4\u8fdb\u4e00\u6b65\u200b\u7684\u200b\uff0c\u200b\u5982\u679c\u200b\u4f60\u200b\u53d1\u73b0\u200bConfig\u200b\u4e2d\u200b\u7684\u200b\u540d\u5b57\u200b\u5bf9\u4e8e\u200b\u547d\u4ee4\u884c\u200b\u6765\u8bf4\u200b\u8fc7\u957f\u200b\uff0c\u200b\u4f60\u200b\u53ef\u4ee5\u200b\u7b80\u5355\u200b\u7684\u200b\u8c03\u7528\u200bself.add_argument\u200b\u5e76\u200b\u8bbe\u7f6e\u200b\u6070\u5f53\u200b\u7684\u200bdest\u200b\u6765\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u4f7f\u7528\u200b\u66f4\u200b\u77ed\u200b\u7684\u200b\u540d\u5b57\u200b\uff0c\u200b\u6b63\u5982\u200bargparse\u200b\u6240\u200b\u505a\u200b\u7684\u200b\u90a3\u6837\u200b\u3002
from chanfig import Config, Variable\nclass Model:\ndef __init__(self, encoder, dropout=0.1, activation='ReLU'):\nself.encoder = Encoder(**encoder)\nself.dropout = Dropout(dropout)\nself.activation = getattr(Activation, activation)\ndef main(config):\nmodel = Model(**config.model)\noptimizer = Optimizer(**config.optimizer)\nscheduler = Scheduler(**config.scheduler)\ndataset = Dataset(**config.dataset)\ndataloader = Dataloader(**config.dataloader)\nclass TestConfig(Config):\ndef __init__(self):\nsuper().__init__()\ndropout = Variable(0.1)\nself.name = \"CHANfiG\"\nself.seed = 1013\nself.data.batch_size = 64\nself.model.encoder.num_layers = 6\nself.model.decoder.num_layers = 6\nself.model.dropout = dropout\nself.model.encoder.dropout = dropout\nself.model.decoder.dropout = dropout\nself.activation = \"GELU\"\nself.optim.lr = 1e-3\nself.add_argument(\"--batch_size\", dest=\"data.batch_size\")\nself.add_argument(\"--lr\", dest=\"optim.lr\")\ndef post(self):\nself.id = f\"{self.name}_{self.seed}\"\nif __name__ == '__main__':\n# config = Config.load('config.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b yaml\n# config = Config.load('config.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b json\n# existing_configs = {'data.batch_size': 64, 'model.encoder.num_layers': 8}\n# config = Config(**existing_configs) # \u200b\u5982\u679c\u200b\u4f60\u200b\u6709\u4e9b\u200bconfig\u200b\u9700\u8981\u200b\u8bfb\u53d6\u200b\nconfig = TestConfig()\nconfig = config.parse()\n# config.merge('dataset.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u5408\u5e76\u200b\u4e00\u4e2a\u200b yaml\n# config.merge('dataset.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u5408\u5e76\u200b\u4e00\u4e2a\u200b json\n# \u200b\u6ce8\u610f\u200b\u88ab\u200b\u5408\u5e76\u200b\u7684\u200b\u503c\u200b\u5177\u6709\u200b\u66f4\u200b\u9ad8\u200b\u7684\u200b\u4f18\u5148\u7ea7\u200b\nconfig.model.decoder.num_layers = 8\nconfig.freeze()\nprint(config)\n# main(config)\n# config.yaml('config.yaml') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u4fdd\u5b58\u200b\u4e00\u4e2a\u200b yaml\n# config.json('config.json') # \u200b\u5982\u679c\u200b\u4f60\u200b\u60f3\u200b\u4fdd\u5b58\u200b\u4e00\u4e2a\u200b json\n\u200b\u6240\u6709\u200b\u4f60\u200b\u9700\u8981\u200b\u505a\u200b\u7684\u200b\u4ec5\u4ec5\u200b\u662f\u200b\u8fd0\u884c\u200b\u4e00\u884c\u200b\uff1a
Bashpython main.py --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\n\u200b\u5f53\u7136\u200b\uff0c\u200b\u4f60\u200b\u4e5f\u200b\u53ef\u4ee5\u200b\u8bfb\u53d6\u200b\u4e00\u4e2a\u200b\u9ed8\u8ba4\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u7136\u540e\u200b\u5728\u200b\u4ed6\u200b\u57fa\u7840\u200b\u4e0a\u200b\u4fee\u6539\u200b\uff1a
\u200b\u6ce8\u610f\u200b\uff0c\u200b\u4f60\u200b\u5fc5\u987b\u200b\u6307\u5b9a\u200bconfig.parse(default_config='config')\u200b\u6765\u200b\u6b63\u786e\u200b\u8bfb\u53d6\u200b\u9ed8\u8ba4\u200b\u914d\u7f6e\u6587\u4ef6\u200b\u3002
python main.py --config meow.yaml --model.encoder.num_layers 8 --model.dropout=0.2 --lr 5e-3\n\u200b\u5982\u679c\u200b\u4f60\u200b\u4fdd\u5b58\u200b\u4e86\u200b\u914d\u7f6e\u6587\u4ef6\u200b\uff0c\u200b\u90a3\u200b\u4ed6\u200b\u5e94\u8be5\u200b\u770b\u8d77\u6765\u200b\u50cf\u200b\u8fd9\u6837\u200b\uff1a
YAMLactivation: GELU\ndata:\nbatch_size: 64\nid: CHANfiG_1013\nmodel:\ndecoder:\ndropout: 0.1\nnum_layers: 6\ndropout: 0.1\nencoder:\ndropout: 0.1\nnum_layers: 6\nname: CHANfiG\noptim:\nlr: 0.005\nseed: 1013\n{\n\"name\": \"CHANfiG\",\n\"seed\": 1013,\n\"data\": {\n\"batch_size\": 64\n},\n\"model\": {\n\"encoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"decoder\": {\n\"num_layers\": 6,\n\"dropout\": 0.1\n},\n\"dropout\": 0.1\n},\n\"activation\": \"GELU\",\n\"optim\": {\n\"lr\": 0.005\n},\n\"id\": \"CHANfiG_1013\"\n}\n\u200b\u5728\u200b\u65b9\u6cd5\u200b\u4e2d\u200b\u5b9a\u4e49\u200b\u9ed8\u8ba4\u200b\u53c2\u6570\u200b\uff0c\u200b\u5728\u200b\u547d\u4ee4\u884c\u200b\u4e2d\u200b\u4fee\u6539\u200b\uff0c\u200b\u7136\u540e\u200b\u5c06\u200b\u5269\u4e0b\u200b\u7684\u200b\u4ea4\u7ed9\u200b CHANfiG\u3002
"},{"location":"zh/#_6","title":"\u5b89\u88c5","text":"\u200b\u5b89\u88c5\u200b pypi \u200b\u4e0a\u200b\u6700\u8fd1\u200b\u7684\u200b\u7a33\u5b9a\u200b\u7248\u672c\u200b\uff1a
Bashpip install chanfig\n\u200b\u4ece\u200b\u6e90\u7801\u200b\u5b89\u88c5\u200b\u6700\u65b0\u200b\u7684\u200b\u7248\u672c\u200b\uff1a
Bashpip install git+https://github.com/ZhiyuanChen/CHANfiG\n\u200b\u4ed6\u200b\u672c\u8be5\u5982\u6b64\u200b\u5de5\u4f5c\u200b\u3002
"},{"location":"zh/#_7","title":"\u6388\u6743","text":"CHANfiG \u200b\u4f9d\u636e\u200b\u4e0b\u5217\u200b\u8bb8\u53ef\u8bc1\u200b\u8fdb\u884c\u200b\u591a\u91cd\u200b\u6388\u6743\u200b\uff1a
\u200b\u5982\u679c\u200b\u4f60\u200b\u4f7f\u7528\u200b\u672c\u200b\u5de5\u4f5c\u200b\uff0c\u200b\u4f60\u200b\u53ef\u4ee5\u200b\u4ece\u4e2d\u200b\u4efb\u9009\u200b\uff08\u200b\u4e00\u4e2a\u200b\u6216\u8005\u200b\u591a\u4e2a\u200b\uff09\u200b\u8bb8\u53ef\u8bc1\u200b\u3002
SPDX-License-Identifier: Unlicense OR AGPL-3.0-or-later OR GPL-2.0-or-later OR BSD-4-Clause OR MIT OR Apache-2.0