# classconfig
Package for creating (yaml) configuration files automatically and loading objects from those configuration files.
## Installation
You can install it using pip:
pip install classconfig
## Usage
At first we need a class that is configurable it means that it has `ConfigurableAttribute` class members. Such as
`ConfigurableValue` or `ConfigurableFactory`. Let's create two simple classes where one of them will have the other
instance as a member:
```python
from classconfig import ConfigurableValue, ConfigurableFactory, ConfigurableMixin
class Inventory(ConfigurableMixin):
size: int = ConfigurableValue(desc="Size of an inventory", user_default=10, validator=lambda x: x > 0)
class Character(ConfigurableMixin):
lvl: int = ConfigurableValue(desc="Level of a character", user_default=1, validator=lambda x: x > 0)
name: str = ConfigurableValue(desc="Name of a character")
inventory: Inventory = ConfigurableFactory(desc="Character's inventory", cls_type=Inventory)
```
You can see that the usage is similar to dataclasses as it also uses descriptors. You can omit the `ConfigurableMixin`
inheritance but then you will have to write your own `__init__` method e.g.:
```python
class Inventory:
size: int = ConfigurableValue(desc="Size of an inventory", user_default=10, validator=lambda x: x > 0)
def __init__(self, size: int):
self.size = size
```
### Creating configuration file
Now let's create a configuration file for our `Character` class. You can do it by calling `save` method of `Config` class:
```python
from classconfig import Config
Config(Character).save("config.yaml")
```
You will get a file with the following content:
```yaml
lvl: 1 # Level of a character
name: # Name of a character
inventory: # Character's inventory
size: 10 # Size of an inventory
```
### Validation
As you have seen in the previous example, it is possible to add a validator.
A validator could be any callable that takes one argument and return `True` when valid.
You can also raise an exception if the argument is invalid to specify the reason for the failure.
There are various predefined validators in `classconfig.validators` module.
### Transformation
It is possible to specify a transformation (`transform` attribute) that will transform user input. The transformation
is done before the validation. Thus, it can be used to transform input into valid form.
It can be any callable that takes one argument and returns the transformed value, but there also exist some predefined
transformations in `classconfig.transforms` module.
### Loading
Now let's load the configuration file we just created and create an instance of `Character` class:
```python
from classconfig import Config, ConfigurableFactory
config = Config(Character).load(path) # load configuration file
loaded_obj = ConfigurableFactory(Character).create(config) # create an instance of Character class
```
## Why YAML?
YAML is a human-readable data serialization language. It is easy to read and write. It is also easy to parse and
generate.
It supports hierarchical data structures, which are very useful when you need to represent configuration
of a class that has other configurable classes as members.
It supports comments, unlike e.g. json, which is also a big advantage.
Raw data
{
"_id": null,
"home_page": "https://github.com/mdocekal/classconfig",
"name": "classconfig",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "configuration,auto config,config,configurable,configurable class,configurable object,configurable attribute",
"author": "Martin Do\u010dekal",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/ce/a2/98063c5395ba8add89202a05afaa39e7d45d546249e7fdf1a496734ee9fe/classconfig-1.0.5.tar.gz",
"platform": null,
"description": "# classconfig\nPackage for creating (yaml) configuration files automatically and loading objects from those configuration files.\n\n## Installation\nYou can install it using pip:\n\n pip install classconfig\n\n## Usage\nAt first we need a class that is configurable it means that it has `ConfigurableAttribute` class members. Such as\n`ConfigurableValue` or `ConfigurableFactory`. Let's create two simple classes where one of them will have the other \ninstance as a member:\n\n```python\nfrom classconfig import ConfigurableValue, ConfigurableFactory, ConfigurableMixin\n\n\nclass Inventory(ConfigurableMixin):\n size: int = ConfigurableValue(desc=\"Size of an inventory\", user_default=10, validator=lambda x: x > 0)\n\n\nclass Character(ConfigurableMixin):\n lvl: int = ConfigurableValue(desc=\"Level of a character\", user_default=1, validator=lambda x: x > 0)\n name: str = ConfigurableValue(desc=\"Name of a character\")\n inventory: Inventory = ConfigurableFactory(desc=\"Character's inventory\", cls_type=Inventory)\n\n```\n\nYou can see that the usage is similar to dataclasses as it also uses descriptors. You can omit the `ConfigurableMixin`\ninheritance but then you will have to write your own `__init__` method e.g.:\n\n```python\nclass Inventory:\n size: int = ConfigurableValue(desc=\"Size of an inventory\", user_default=10, validator=lambda x: x > 0)\n\n def __init__(self, size: int):\n self.size = size\n```\n\n### Creating configuration file\nNow let's create a configuration file for our `Character` class. You can do it by calling `save` method of `Config` class:\n\n```python\nfrom classconfig import Config\n\nConfig(Character).save(\"config.yaml\")\n```\n\nYou will get a file with the following content:\n\n\n```yaml\nlvl: 1 # Level of a character\nname: # Name of a character\ninventory: # Character's inventory\n size: 10 # Size of an inventory\n```\n\n### Validation\nAs you have seen in the previous example, it is possible to add a validator. \nA validator could be any callable that takes one argument and return `True` when valid. \nYou can also raise an exception if the argument is invalid to specify the reason for the failure.\n\nThere are various predefined validators in `classconfig.validators` module.\n\n### Transformation\nIt is possible to specify a transformation (`transform` attribute) that will transform user input. The transformation\nis done before the validation. Thus, it can be used to transform input into valid form.\n\nIt can be any callable that takes one argument and returns the transformed value, but there also exist some predefined\ntransformations in `classconfig.transforms` module.\n\n\n### Loading\nNow let's load the configuration file we just created and create an instance of `Character` class:\n\n```python\nfrom classconfig import Config, ConfigurableFactory\n\nconfig = Config(Character).load(path) # load configuration file\nloaded_obj = ConfigurableFactory(Character).create(config) # create an instance of Character class\n```\n\n## Why YAML?\nYAML is a human-readable data serialization language. It is easy to read and write. It is also easy to parse and\ngenerate.\n\nIt supports hierarchical data structures, which are very useful when you need to represent configuration \nof a class that has other configurable classes as members.\n\nIt supports comments, unlike e.g. json, which is also a big advantage.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Package for creating configuration files automatically and loading objects from those configuration files.",
"version": "1.0.5",
"project_urls": {
"Homepage": "https://github.com/mdocekal/classconfig"
},
"split_keywords": [
"configuration",
"auto config",
"config",
"configurable",
"configurable class",
"configurable object",
"configurable attribute"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a337e126075765eaa159e13b5296fee052a5f134f8c8eea1e8e29fefeca4db2d",
"md5": "30a4184f3bad1b1a6418de20b4863511",
"sha256": "414599f3de06c6dc3b34eac30ba713a9e27293f28ecda5df641383634d922e4c"
},
"downloads": -1,
"filename": "classconfig-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30a4184f3bad1b1a6418de20b4863511",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17782,
"upload_time": "2023-11-22T15:42:24",
"upload_time_iso_8601": "2023-11-22T15:42:24.077378Z",
"url": "https://files.pythonhosted.org/packages/a3/37/e126075765eaa159e13b5296fee052a5f134f8c8eea1e8e29fefeca4db2d/classconfig-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cea298063c5395ba8add89202a05afaa39e7d45d546249e7fdf1a496734ee9fe",
"md5": "c09fab1553837df4fea5331e7f44f75d",
"sha256": "85f8a1b0e19d2b8410993dcdee41d0a2756bceb46b1b525e21ab19a7d07d65de"
},
"downloads": -1,
"filename": "classconfig-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "c09fab1553837df4fea5331e7f44f75d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22403,
"upload_time": "2023-11-22T15:42:25",
"upload_time_iso_8601": "2023-11-22T15:42:25.526008Z",
"url": "https://files.pythonhosted.org/packages/ce/a2/98063c5395ba8add89202a05afaa39e7d45d546249e7fdf1a496734ee9fe/classconfig-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-22 15:42:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdocekal",
"github_project": "classconfig",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "classconfig"
}
JSON
