[](https://circleci.com/gh/infoscout/garlicconfig)
[](https://codecov.io/gh/infoscout/garlicconfig)
# GarlicConfig
GarlicConfig is a framework that makes it easy to deal with configurations in an easy yet flexible way. The core of this package is written in C++ and this Python package wraps the native code to provide an easy access to the configuration and some extra feature on top of it. The native library allows for quick retrieval of the configurations which can be used on any platform, this wrapper, however allows for defining advanced validation and config retrieval logic. For example, you could define your own conventions for getting localized version of configs.
The whole thing starts by defining the structure of your configs using models.
You can define models by inheriting from `ConfigModel`:
```python
from garlicconfig import models
class DatabaseConfig(models.ConfigModel):
pass
```
By adding attributes (or properties), you can define what this model recognizes and what format should each one of these attributes have.
For properties, you can use `ConfigField`. There are a set of built-in fields:
* StringField
* IntegerField
* ArrayField
* ModelField
* BooleanField
You can also make your own custom `ConfigModel` and/or `ConfigField`.
for example:
```python
from garlicconfig import fields
from garlicconfig.exceptions import ValidationError
class EvenIntegerField(IntegerField):
def validate(self, value):
if value % 2 != 0:
raise ValidationError('bad integer')
def to_model_value(self, value):
return int(value)
def to_garlic_value(self, value):
return str(value)
```
The field class above stores `str` in the python dictionary representation. However, for the materialized config model, `int` is used. It also invalidates unaccepted values by raising `ValidationError`, in this case odd values.
Note that `to_model_value` is responsible for converting a basic type to a more complicated python type, perhaps constructing a Python-defined class.
`to_garlic_value` does the exact opposite, it should convert the value to a basic value. Basic value is defined to be one of the following types:
* **str**
* **int**
* **float**
* **dict**
* **set** & **list**
This is primarily used for ease of encoding/decoding. By default, both of these methods return the given `value` without making any changes and I'd recommend not creating very complicated objects since it'll limit the accessibility of them in different platforms should you need to support them.
Next, you can define your own config model and use the custom `ConfigField` we just created.
for example:
```python
class SomeRandomConfig(ConfigModel):
value = EvenIntegerField(nullable=False, default=2)
```
You can use `py_value` method on config models to get a python dictionary with basic value types in it. This is handy to cache it in memory, or to use it for serialization.
`from_dict` will create a new config model from a python dictionary.
Furthermore, you can use `garlic_value` to construct a `GarlicValue` from the current config model and use `from_garlic` to construct a model from a `GarlicValue`.
`GarlicValue` is a type that keeps configuration objects in the native code and loads them in Python lazily. This allows you to lower memory usage while speeding up all operations. It also comes with a set of handy methods:
### resolve
Allows for requested a specific value by providing a dot separated path.
for example:
```python
class ParentConfig(models.ConfigModel):
random_config_field = models.ModelField(SomeRandomConfig)
foo = ParentConfig()
foo.random_config_field.value = 8
garlic_value = foo.garlic_value()
print(garlic_value.resolve('random_config_field.value'))
```
In the above code, if value to the given path exists, the python representation of the value gets returned. Otherwise, `None` gets returned. This is helpful because you can simply give the path to the final value and get the requested value. Since all of this is happening in the native code, it's significantly faster to use `GarlicValue` over python dictionary or regular models.
Your goal should be to validate models using `ConfigModel` and store/read configurations using `GarlicValue`.
### clone
Copy operations, specially deep copies in Python are very expensive. You can, however, clone `GarlicValue` instances much faster by using the native clone which copies the object without the need to use deep copy yet accomplish the same result.
for example:
```python
garlic_value_1 = foo.garlic_value()
garlic_value_2 = foo.clone()
```
# Serialization
You can use the following code to encode/decode configs. The default encoder is Json. However, you can write your own encoder and support other formats as needed.
```python
from garlicconfig import encoding
config = DatabaseConfig()
serialized_string = encoding.encode(config, pretty=True)
```
# Merging layers
You merge two configuration layers in order to support inheritance. Something that will come very handy if you plan to use localization or multi-layered configurations.
Any `GarlicValue` instance will have a `apply` method that will basically applies a second `GarlicValue` on top of itself.
for example:
```python
from garlicconfig import models
from garlicconfig import fields
class ExtraConfig(models.ConfigModel):
has_id = fields.BooleanField(default=False)
has_degree = fields.BooleanField(default=False)
class DumbConfig(models.ConfigModel):
name = fields.StringField(nullable=False)
numbers = fields.ArrayField(IntegerField())
extra = models.ModelField(ExtraConfig)
def validate(self):
super(DumbConfig, self).validate()
if not self.name and not self.numbers:
raise garlicconfig.exceptions.ValidationError('invalid config for some reason!')
config_1 = DumbConfig.from_dict({
'name': 'Peyman',
'numbers': [1, 2, 3]
'extra': {
'has_id': True
}
}).garlic_value()
config_2 = DumbConfig.from_dict({
'name': 'Patrick',
'numbers': [4, 5, 6]
'extra': {
'has_degree': True
}
}).garlic_value()
config_1.apply(config_2)
config_1.resolve('numbers') # returns [4, 5, 6]
config_1.resolve('name') # returns 'Patrick'
config_1.resolve('extra.has_id') # returns True (from config_1)
config_1.resolve('extra.has_degree') # returns True (from config_2)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/infoscout/garlicconfig",
"name": "garlicconfig",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "configs,settings",
"author": "Infoscout",
"author_email": "infoscout@gmail.com",
"download_url": "https://github.com/infoscout/garlicconfig/archive/1.2.5.tar.gz",
"platform": null,
"description": "[](https://circleci.com/gh/infoscout/garlicconfig)\n[](https://codecov.io/gh/infoscout/garlicconfig)\n\n# GarlicConfig\n\nGarlicConfig is a framework that makes it easy to deal with configurations in an easy yet flexible way. The core of this package is written in C++ and this Python package wraps the native code to provide an easy access to the configuration and some extra feature on top of it. The native library allows for quick retrieval of the configurations which can be used on any platform, this wrapper, however allows for defining advanced validation and config retrieval logic. For example, you could define your own conventions for getting localized version of configs.\n\nThe whole thing starts by defining the structure of your configs using models.\n\nYou can define models by inheriting from `ConfigModel`:\n\n```python\nfrom garlicconfig import models\n\nclass DatabaseConfig(models.ConfigModel):\n pass\n```\n\nBy adding attributes (or properties), you can define what this model recognizes and what format should each one of these attributes have.\n\nFor properties, you can use `ConfigField`. There are a set of built-in fields:\n\n* StringField\n* IntegerField\n* ArrayField\n* ModelField\n* BooleanField\n\n\nYou can also make your own custom `ConfigModel` and/or `ConfigField`.\n\nfor example:\n\n```python\nfrom garlicconfig import fields\nfrom garlicconfig.exceptions import ValidationError\n\nclass EvenIntegerField(IntegerField):\n\n def validate(self, value):\n if value % 2 != 0:\n raise ValidationError('bad integer')\n \n def to_model_value(self, value):\n return int(value)\n \n def to_garlic_value(self, value):\n return str(value)\n```\n\nThe field class above stores `str` in the python dictionary representation. However, for the materialized config model, `int` is used. It also invalidates unaccepted values by raising `ValidationError`, in this case odd values.\n\nNote that `to_model_value` is responsible for converting a basic type to a more complicated python type, perhaps constructing a Python-defined class.\n\n`to_garlic_value` does the exact opposite, it should convert the value to a basic value. Basic value is defined to be one of the following types:\n\n* **str**\n* **int**\n* **float**\n* **dict**\n* **set** & **list**\n\nThis is primarily used for ease of encoding/decoding. By default, both of these methods return the given `value` without making any changes and I'd recommend not creating very complicated objects since it'll limit the accessibility of them in different platforms should you need to support them.\n\nNext, you can define your own config model and use the custom `ConfigField` we just created.\n\nfor example:\n\n```python\nclass SomeRandomConfig(ConfigModel):\n\n\tvalue = EvenIntegerField(nullable=False, default=2)\n```\n\nYou can use `py_value` method on config models to get a python dictionary with basic value types in it. This is handy to cache it in memory, or to use it for serialization.\n\n`from_dict` will create a new config model from a python dictionary.\n\nFurthermore, you can use `garlic_value` to construct a `GarlicValue` from the current config model and use `from_garlic` to construct a model from a `GarlicValue`.\n\n`GarlicValue` is a type that keeps configuration objects in the native code and loads them in Python lazily. This allows you to lower memory usage while speeding up all operations. It also comes with a set of handy methods:\n\n### resolve\nAllows for requested a specific value by providing a dot separated path.\n\nfor example:\n\n```python\nclass ParentConfig(models.ConfigModel):\n \n random_config_field = models.ModelField(SomeRandomConfig)\n\n\nfoo = ParentConfig()\nfoo.random_config_field.value = 8\ngarlic_value = foo.garlic_value()\nprint(garlic_value.resolve('random_config_field.value'))\n```\nIn the above code, if value to the given path exists, the python representation of the value gets returned. Otherwise, `None` gets returned. This is helpful because you can simply give the path to the final value and get the requested value. Since all of this is happening in the native code, it's significantly faster to use `GarlicValue` over python dictionary or regular models.\n\nYour goal should be to validate models using `ConfigModel` and store/read configurations using `GarlicValue`.\n\n### clone\nCopy operations, specially deep copies in Python are very expensive. You can, however, clone `GarlicValue` instances much faster by using the native clone which copies the object without the need to use deep copy yet accomplish the same result.\n\nfor example:\n\n```python\ngarlic_value_1 = foo.garlic_value()\ngarlic_value_2 = foo.clone()\n```\n\n# Serialization\n\nYou can use the following code to encode/decode configs. The default encoder is Json. However, you can write your own encoder and support other formats as needed.\n\n```python\nfrom garlicconfig import encoding\n\nconfig = DatabaseConfig()\nserialized_string = encoding.encode(config, pretty=True)\n```\n\n\n# Merging layers\n\nYou merge two configuration layers in order to support inheritance. Something that will come very handy if you plan to use localization or multi-layered configurations.\n\nAny `GarlicValue` instance will have a `apply` method that will basically applies a second `GarlicValue` on top of itself.\n\nfor example:\n\n```python\nfrom garlicconfig import models\nfrom garlicconfig import fields\n\n\nclass ExtraConfig(models.ConfigModel):\n\n has_id = fields.BooleanField(default=False)\n has_degree = fields.BooleanField(default=False)\n\n\nclass DumbConfig(models.ConfigModel):\n\n name = fields.StringField(nullable=False)\n numbers = fields.ArrayField(IntegerField())\n extra = models.ModelField(ExtraConfig)\n \n def validate(self):\n super(DumbConfig, self).validate()\n if not self.name and not self.numbers:\n raise garlicconfig.exceptions.ValidationError('invalid config for some reason!')\n\n\nconfig_1 = DumbConfig.from_dict({\n 'name': 'Peyman',\n 'numbers': [1, 2, 3]\n 'extra': {\n 'has_id': True\n }\n}).garlic_value()\n\nconfig_2 = DumbConfig.from_dict({\n 'name': 'Patrick',\n 'numbers': [4, 5, 6]\n 'extra': {\n 'has_degree': True\n }\n}).garlic_value()\n\nconfig_1.apply(config_2)\nconfig_1.resolve('numbers') # returns [4, 5, 6]\nconfig_1.resolve('name') # returns 'Patrick'\nconfig_1.resolve('extra.has_id') # returns True (from config_1)\nconfig_1.resolve('extra.has_degree') # returns True (from config_2)\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "InfoScout GarlicConfig",
"version": "1.2.5",
"split_keywords": [
"configs",
"settings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8022e292b6a72c436889e5064d7b9b14f8a7d9fc49a8c7827719147e09687c11",
"md5": "6cfc391fdcd907d90427a1502e65ea12",
"sha256": "fd0183dd6b12ed14c0dd2c95a6711250915897eb03f1d28701380044e2feb7ec"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp36-cp36m-manylinux_2_24_x86_64.whl",
"has_sig": false,
"md5_digest": "6cfc391fdcd907d90427a1502e65ea12",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": null,
"size": 1389166,
"upload_time": "2023-01-11T19:51:03",
"upload_time_iso_8601": "2023-01-11T19:51:03.185359Z",
"url": "https://files.pythonhosted.org/packages/80/22/e292b6a72c436889e5064d7b9b14f8a7d9fc49a8c7827719147e09687c11/garlicconfig-1.2.5-cp36-cp36m-manylinux_2_24_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bee5cb71e4738bff5327a8347890b5f3277473edb43666f2a356b0cfe7d85f7c",
"md5": "c253f3cd6aee6117162a7830af9b67fe",
"sha256": "16cb8a7d5119a4ae000349da1ba3ceeb6ceff8176384f22d765c5547c42d00aa"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp36-cp36m-win32.whl",
"has_sig": false,
"md5_digest": "c253f3cd6aee6117162a7830af9b67fe",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": null,
"size": 425627,
"upload_time": "2023-01-11T19:50:57",
"upload_time_iso_8601": "2023-01-11T19:50:57.626747Z",
"url": "https://files.pythonhosted.org/packages/be/e5/cb71e4738bff5327a8347890b5f3277473edb43666f2a356b0cfe7d85f7c/garlicconfig-1.2.5-cp36-cp36m-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5f1580c2f9839b6eba58daa6c6cb2f6aeeab9de4636f2a1d58cb1cdab46ab5f",
"md5": "2e7f4fab259d486d78b1f204e5a59967",
"sha256": "73f435e0b9fc8f7362c37889245158be9a2b50441c86b13bd2c9a792680b5351"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp36-cp36m-win_amd64.whl",
"has_sig": false,
"md5_digest": "2e7f4fab259d486d78b1f204e5a59967",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": null,
"size": 458443,
"upload_time": "2023-01-11T19:50:42",
"upload_time_iso_8601": "2023-01-11T19:50:42.600434Z",
"url": "https://files.pythonhosted.org/packages/c5/f1/580c2f9839b6eba58daa6c6cb2f6aeeab9de4636f2a1d58cb1cdab46ab5f/garlicconfig-1.2.5-cp36-cp36m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "799a2dffb81e336ad58de87e830c352f0249507eb7d3eb2a36521f92d18c43bb",
"md5": "b07bef8826822f5bbf8f0c6c16e2383b",
"sha256": "016b0997e4ee4901d521d3444d84bf867f114964ae7ad989194564b0da69bc22"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp37-cp37m-win32.whl",
"has_sig": false,
"md5_digest": "b07bef8826822f5bbf8f0c6c16e2383b",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 410318,
"upload_time": "2023-01-11T19:50:47",
"upload_time_iso_8601": "2023-01-11T19:50:47.040709Z",
"url": "https://files.pythonhosted.org/packages/79/9a/2dffb81e336ad58de87e830c352f0249507eb7d3eb2a36521f92d18c43bb/garlicconfig-1.2.5-cp37-cp37m-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "126eba6ad41966f3682a6904b12786067976dae35dda05efa6b64fd8e87dcc6b",
"md5": "830f6f94fe9b58659af0bd629e413640",
"sha256": "1374ae818aaa5b44ebeb826fe00e1e3ee07a47138bc088911ed2f1ad972d9323"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp37-cp37m-win_amd64.whl",
"has_sig": false,
"md5_digest": "830f6f94fe9b58659af0bd629e413640",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 435899,
"upload_time": "2023-01-11T19:50:38",
"upload_time_iso_8601": "2023-01-11T19:50:38.248506Z",
"url": "https://files.pythonhosted.org/packages/12/6e/ba6ad41966f3682a6904b12786067976dae35dda05efa6b64fd8e87dcc6b/garlicconfig-1.2.5-cp37-cp37m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "247055587eebb2bfc44c947ec63befc308f2848eb0d77bbf8342ed5f070158a0",
"md5": "fa5d8247ac4e2551c3342d6d197e7495",
"sha256": "65288d521d710073dd0f711cb391dd75370ec6acedd951f0a31a0e79a25a7875"
},
"downloads": -1,
"filename": "garlicconfig-1.2.5-cp39-cp39-macosx_12_0_x86_64.whl",
"has_sig": false,
"md5_digest": "fa5d8247ac4e2551c3342d6d197e7495",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 452416,
"upload_time": "2023-01-11T19:50:28",
"upload_time_iso_8601": "2023-01-11T19:50:28.669171Z",
"url": "https://files.pythonhosted.org/packages/24/70/55587eebb2bfc44c947ec63befc308f2848eb0d77bbf8342ed5f070158a0/garlicconfig-1.2.5-cp39-cp39-macosx_12_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 19:51:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "infoscout",
"github_project": "garlicconfig",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "Cython",
"specs": [
[
"==",
"0.28.5"
]
]
},
{
"name": "cget",
"specs": [
[
"==",
"0.1.6"
]
]
},
{
"name": "cmake",
"specs": [
[
"==",
"3.12.0"
]
]
}
],
"lcname": "garlicconfig"
}
JSON
