| Name | generic-configuration-builder JSON |
| Version |
1.2.2
JSON |
| download |
| home_page | None |
| Summary | A simple library for parsing a configuration file format which is intended to build dependencies and hold parameters - well suited for experimentaton settings in which different experiments use different clases. |
| upload_time | 2024-04-04 10:36:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
configuration
config
experiment
dependencies
setup
parameters
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Generic-Configuration-Builder
This library intends to help separate the setup and execution of experiments. If you need a bunch of different main classes to store the setup of your experiments, then this tiny library can help!
The library parses a file format that can be used to set up any kind of class dependencies including all parameters, while also leaving the option to input additional parameters into the setup.
## Installation
```
pip install generic_configuration_builder
```
## How to use
With a prepared configuration simply call:
```
from generic_configuration_builder import gcb_build
instances_dictionary = gcb_build("path/to/configuration.ini")
```
## Configuration Syntax
The .ini file format is used as follows:
```
[instance_name]
~Module = module_of.the_class
~Class = ClassName
constructor_argument_1 = 42
constructor_argument_2 = "int, strings, lists, dicts, tuples and None are supported"
constructor_argument_3 = [1,2,3,4]
constructor_argument_4 = (5,6,7,8)
constructor_argument_5 = {"key_1": "value_1",
"key_2": None}
[another_instance]
~MODULE = a_different.module
~CLASS = DifferentClass
argument_that_requieres_the_previous_class = *instance_name
more_arguments = ["a", 2]
[~RETURN]
RETURN = [instance_name, another_instance]
```
Each instance has a name that is given in brackets [].
After the name follows the module and the class name of the class that is supposed to be instantiated here, indicated by the `~MODULE` and `~CLASS` keywords.
Then the arguments that will be passed to the constructor follow with the name of the argument leading, the equal sign and the value follow. The basic python built-in types are supported here. <br>
Previously defined instances can be used as arguments to other instances by using a * followed by a previously defined instance name.<br>
Optionally at the end of the configuration, you may define a `~RETURN` section which specifies which instances will be returned by the `.gcb_build()` function as a dictionary. In this dictionary the instance names are the keys and the initialized instances are the values. If this section is not defined only the last created instance in the configuration file is returned as a single object (not a dictionary).
## Other features
### Placeholder variables
If you don't want to fix all parameters in the configuration you can write placeholders in the same way as you do with previously defined instances.
```
[thingy]
~MODULE = module_of.thingy
~CLASS = ThingyClass
argument_i_dont_want_to_define_in_config = *name_of_argument
...
```
To fill `name_of_argument` with a value, pass a keyword argument with the same name to the `gcb_build()` function. For example:
```
from generic_configuration_builder import gcb_build
instances_dictionary = gcb_build("path/to/configuration.ini",
name_of_argument = 42)
```
Here there is no restriction on datatypes. You may pass any object like this.
### Default values for placeholders
If you only sometimes want to change a parameter but most of the time want to use a default value you can use default values defined in a `~DEFAULT` section as follows:
```
[~DEFAULT]
name_of_argument = "This is the default value for this argument."
funny_number = 24
...
```
The default value can be overwritten by passing an according keyword argument to the `gcb_build()` function as follows:
```
instances_dictionary = gcb_build("path/to/configuration.ini", name_of_argument="this_string_overwrites_the_default",
funny_number=25)
```
### Use child objects as arguments
If you want to pass the child object of some instance to another instance you can do it the same why as you would in python by using dots `.`
```
...
[foo]
~MODULE = foos.module
~CLASS = FooClass
argument_that_needs_chield_from previous_instance = *name_of_previous_instance.child
```
This works recursively, so you could write `*instance.child.subchild` as well.
### Using nested instances
You can nest an instance inside a list, tuple or dictionary and it will still be recognized. This also works recursively. For example like this:
```
[some_thing]
~MODULE = some
~CLASS = Thing
dict_with_instance = {"object": *this_is_an_instance,
"sub_dictionary": {"sub_dictionary_key": *this_is_another_instance}},
{*instance_as_key : "some value"}
list_of_tuple = [(*instance_1, *instance_2.child, 'a normal string'),
(*instance_3, None, 'another_string')]
```
Note that not all objects can be keys of dictionaries.
### Parsing torch and numpy arrays
If you have numpy or pytorch installed AND the class you want to instantiate uses type hints in the signature of its `__init__` function, then you may pass an array as arguments in addition to the other data types. The correct format here is the one you get when you `print()` the according array or tensor. These special data types can not be nested inside collections.
## Examples
Specific examples without any other python packages are not very helpful as native python classes usually don't need this kind of construction.
So here is a simple example with some made-up classes.
Assume the existence of `classes.py` in the working directory with the following content:
```
class ChildClass():
def __init__(self, some_string: str, some_float: float, another_string: str) -> None:
self.some_string = some_string
self.some_float = some_float
self.combined_string = some_string + str(some_float)
self.another_string = another_string
class ParentClass():
def __init__(self, some_int: int, combined_string: str) -> None:
self.some_int = some_int
self.combined_string = combined_string
```
An `example_config.ini` could look like this:
```
[~DEFAULT]
an_integer = 25
[child_instance]
~MODULE = classes
~CLASS = ChildClass
some_string = "blub"
some_float = 3.141
another_string = *another_string
[parent_instance]
~MODULE = classes
~CLASS = ParentClass
some_int = *an_integer
combined_string = *child_instance.combined_string
[~RETURN]
RETURN = [child_instance, parent_instance, parent_instance.combined_string]
```
Note that `another_string` is not defined in the config and therefore needs to be passed as an argument to `gcb_build()`. The argument `an_integer` has a default value and therefore can be passed optionally to the function as an argument.
This configuration could for example be built as follows:
```
from generic_configuration_builder import gcb_build
instances_dict = gcb_build("./example_config.ini",
another_string = "this is not part ot the config")
```
After execution `instances_dict` contains a dictionary of the instance:
```
{
'child_instance': <classes.ChildClass object at 0x7fd91416ea70>,
'parent_instance': <classes.ParentClass object at 0x7fd91416ec50>,
'parent_instance.combined_string': 'blub3.141'
}
```
Which now can be used in whatever way these objects are intended to be used.
Some extensive examples using a complex class structure can be found [here](https://github.com/Sebastian-Griesbach/Improving-Policy-Conditioned-Value-Functions/tree/main/experiments).
Raw data
{
"_id": null,
"home_page": null,
"name": "generic-configuration-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "configuration, config, experiment, dependencies, setup, parameters",
"author": null,
"author_email": "Sebastian Griesbach <sebastian.griesbach@zoho.eu>",
"download_url": "https://files.pythonhosted.org/packages/2c/6b/a0caa089d9f03562fd1087aae3e7831dc600c15e7870af496d1b1b65a439/generic_configuration_builder-1.2.2.tar.gz",
"platform": null,
"description": "# Generic-Configuration-Builder\nThis library intends to help separate the setup and execution of experiments. If you need a bunch of different main classes to store the setup of your experiments, then this tiny library can help!\nThe library parses a file format that can be used to set up any kind of class dependencies including all parameters, while also leaving the option to input additional parameters into the setup.\n\n## Installation\n```\npip install generic_configuration_builder\n```\n\n## How to use\nWith a prepared configuration simply call:\n```\nfrom generic_configuration_builder import gcb_build\n\ninstances_dictionary = gcb_build(\"path/to/configuration.ini\")\n```\n\n## Configuration Syntax\nThe .ini file format is used as follows:\n\n```\n[instance_name]\n~Module = module_of.the_class\n~Class = ClassName\nconstructor_argument_1 = 42\nconstructor_argument_2 = \"int, strings, lists, dicts, tuples and None are supported\"\nconstructor_argument_3 = [1,2,3,4]\nconstructor_argument_4 = (5,6,7,8)\nconstructor_argument_5 = {\"key_1\": \"value_1\",\n \"key_2\": None}\n\n[another_instance]\n~MODULE = a_different.module\n~CLASS = DifferentClass\nargument_that_requieres_the_previous_class = *instance_name\nmore_arguments = [\"a\", 2]\n\n[~RETURN]\nRETURN = [instance_name, another_instance]\n```\n\nEach instance has a name that is given in brackets [].\nAfter the name follows the module and the class name of the class that is supposed to be instantiated here, indicated by the `~MODULE` and `~CLASS` keywords.\nThen the arguments that will be passed to the constructor follow with the name of the argument leading, the equal sign and the value follow. The basic python built-in types are supported here. <br>\nPreviously defined instances can be used as arguments to other instances by using a * followed by a previously defined instance name.<br>\nOptionally at the end of the configuration, you may define a `~RETURN` section which specifies which instances will be returned by the `.gcb_build()` function as a dictionary. In this dictionary the instance names are the keys and the initialized instances are the values. If this section is not defined only the last created instance in the configuration file is returned as a single object (not a dictionary).\n\n## Other features\n\n### Placeholder variables\nIf you don't want to fix all parameters in the configuration you can write placeholders in the same way as you do with previously defined instances.\n\n```\n[thingy]\n~MODULE = module_of.thingy\n~CLASS = ThingyClass\nargument_i_dont_want_to_define_in_config = *name_of_argument\n...\n```\nTo fill `name_of_argument` with a value, pass a keyword argument with the same name to the `gcb_build()` function. For example:\n```\nfrom generic_configuration_builder import gcb_build\n\ninstances_dictionary = gcb_build(\"path/to/configuration.ini\", \n name_of_argument = 42)\n```\n\nHere there is no restriction on datatypes. You may pass any object like this.\n\n### Default values for placeholders\nIf you only sometimes want to change a parameter but most of the time want to use a default value you can use default values defined in a `~DEFAULT` section as follows:\n\n```\n[~DEFAULT]\nname_of_argument = \"This is the default value for this argument.\"\nfunny_number = 24\n...\n```\nThe default value can be overwritten by passing an according keyword argument to the `gcb_build()` function as follows:\n```\ninstances_dictionary = gcb_build(\"path/to/configuration.ini\", name_of_argument=\"this_string_overwrites_the_default\",\nfunny_number=25)\n```\n\n### Use child objects as arguments\n\nIf you want to pass the child object of some instance to another instance you can do it the same why as you would in python by using dots `.`\n```\n...\n\n[foo]\n~MODULE = foos.module\n~CLASS = FooClass\nargument_that_needs_chield_from previous_instance = *name_of_previous_instance.child\n```\n\nThis works recursively, so you could write `*instance.child.subchild` as well.\n\n### Using nested instances\n\nYou can nest an instance inside a list, tuple or dictionary and it will still be recognized. This also works recursively. For example like this:\n\n```\n[some_thing]\n~MODULE = some\n~CLASS = Thing\ndict_with_instance = {\"object\": *this_is_an_instance, \n \"sub_dictionary\": {\"sub_dictionary_key\": *this_is_another_instance}},\n {*instance_as_key : \"some value\"}\nlist_of_tuple = [(*instance_1, *instance_2.child, 'a normal string'),\n (*instance_3, None, 'another_string')]\n```\nNote that not all objects can be keys of dictionaries.\n\n### Parsing torch and numpy arrays\n\nIf you have numpy or pytorch installed AND the class you want to instantiate uses type hints in the signature of its `__init__` function, then you may pass an array as arguments in addition to the other data types. The correct format here is the one you get when you `print()` the according array or tensor. These special data types can not be nested inside collections.\n\n## Examples \nSpecific examples without any other python packages are not very helpful as native python classes usually don't need this kind of construction. \nSo here is a simple example with some made-up classes.\nAssume the existence of `classes.py` in the working directory with the following content:\n```\nclass ChildClass():\n def __init__(self, some_string: str, some_float: float, another_string: str) -> None:\n self.some_string = some_string\n self.some_float = some_float\n self.combined_string = some_string + str(some_float)\n self.another_string = another_string\n\nclass ParentClass():\n def __init__(self, some_int: int, combined_string: str) -> None:\n self.some_int = some_int\n self.combined_string = combined_string\n```\n\nAn `example_config.ini` could look like this:\n```\n[~DEFAULT]\nan_integer = 25\n\n[child_instance]\n~MODULE = classes\n~CLASS = ChildClass\nsome_string = \"blub\"\nsome_float = 3.141\nanother_string = *another_string\n\n[parent_instance]\n~MODULE = classes\n~CLASS = ParentClass\nsome_int = *an_integer\ncombined_string = *child_instance.combined_string\n\n[~RETURN]\nRETURN = [child_instance, parent_instance, parent_instance.combined_string]\n```\n\nNote that `another_string` is not defined in the config and therefore needs to be passed as an argument to `gcb_build()`. The argument `an_integer` has a default value and therefore can be passed optionally to the function as an argument.\n\nThis configuration could for example be built as follows:\n\n```\nfrom generic_configuration_builder import gcb_build\n\ninstances_dict = gcb_build(\"./example_config.ini\", \n another_string = \"this is not part ot the config\")\n```\n\nAfter execution `instances_dict` contains a dictionary of the instance:\n```\n{\n 'child_instance': <classes.ChildClass object at 0x7fd91416ea70>,\n 'parent_instance': <classes.ParentClass object at 0x7fd91416ec50>,\n 'parent_instance.combined_string': 'blub3.141'\n}\n```\nWhich now can be used in whatever way these objects are intended to be used.\n\nSome extensive examples using a complex class structure can be found [here](https://github.com/Sebastian-Griesbach/Improving-Policy-Conditioned-Value-Functions/tree/main/experiments).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple library for parsing a configuration file format which is intended to build dependencies and hold parameters - well suited for experimentaton settings in which different experiments use different clases.",
"version": "1.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/Sebastian-Griesbach/Generic-Configuration-Builder/issues",
"Homepage": "https://github.com/Sebastian-Griesbach/Generic-Configuration-Builder"
},
"split_keywords": [
"configuration",
" config",
" experiment",
" dependencies",
" setup",
" parameters"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b62cce8c83ff7a21d83534eb7a8b9b17cec6645b22c35d361f80c5083d2c686",
"md5": "3d02441fd2c11d907b7580ad83458cf3",
"sha256": "ee632e46e003548d8dcea6b4957f43e8d0ad117076844d077a38bd183d79ec25"
},
"downloads": -1,
"filename": "generic_configuration_builder-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d02441fd2c11d907b7580ad83458cf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9093,
"upload_time": "2024-04-04T10:36:25",
"upload_time_iso_8601": "2024-04-04T10:36:25.979293Z",
"url": "https://files.pythonhosted.org/packages/9b/62/cce8c83ff7a21d83534eb7a8b9b17cec6645b22c35d361f80c5083d2c686/generic_configuration_builder-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c6ba0caa089d9f03562fd1087aae3e7831dc600c15e7870af496d1b1b65a439",
"md5": "697e9de4cd26f6e03648b670a78ade47",
"sha256": "beb14524f90eb9a05ea6b86a90e9ee8278df3794f272d855fa6874c6a6e6cc96"
},
"downloads": -1,
"filename": "generic_configuration_builder-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "697e9de4cd26f6e03648b670a78ade47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8232,
"upload_time": "2024-04-04T10:36:27",
"upload_time_iso_8601": "2024-04-04T10:36:27.715636Z",
"url": "https://files.pythonhosted.org/packages/2c/6b/a0caa089d9f03562fd1087aae3e7831dc600c15e7870af496d1b1b65a439/generic_configuration_builder-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 10:36:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Sebastian-Griesbach",
"github_project": "Generic-Configuration-Builder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "generic-configuration-builder"
}
