# Klein Config
Module to provide config management
## Usage
```python
from klein_config import get_config
# Can be overriden with env variable MY_CONFIG_SETTING
config = get_config({"my": {"config": {"setting": "initialised value"}})
# Access via `get` accessor with no backup (raises ConfigMissingException if not found).
value = config.get("my.config.setting")
# Access via `get` accessor method with a backup.
backup_value = config.get("not.a.setting", "backup value")
# Access via `dict` (raises KeyError if not found).
same_value = config["my.config.setting"]
# Sub-configs are created if the value is another `dict`.
intermediate_config = config["my.config"]
same_value_again = intermediate_config["setting"]
```
### Structure
Internally the config object uses the ConfigTree structure that is part of pyhocon. This can be traversed easily with the get method using dot notation as outlined above.
### Config Initialisation
The `get_config` function looks for :
- argument `--common` or environmental variable `KLEIN_COMMON` to specify a valid filepath for a common config file (in either JSON or YAML format); and
- argument `--config` or environmental variable `KLEIN_CONFIG` to specify a valid filepath for a config file
N.B. Passing both environmental variables _and_ arguments for either config or common is ambiguous and is therefore NOT accepted.
You can also pass a `dict` into the `get_config` function.
#### Example configs
JSON:
```json
{
"rabbitmq": {
"host": [
"localhost"
],
"port": 5672,
"username": "username",
"password": "password"
},
"mongo": {
"host": [
"mongo.domain.com"
],
"username": "username",
"password": "password"
}
}
```
YAML:
```yaml
mongo:
host:
- mongo.domain.com
password: password
username: username
rabbitmq:
host:
- localhost
password: username
port: 5672
username: password
```
Example config files are also provided in [json](example.config.json) and [yaml](example.config.yaml) formats.
### Order precedence
The configs are applied to the config object in the following order:
1. Common config as identified via argument `--common` or environmental variable `KLEIN_COMMON`
2. Config that is injected via the Class constructor
3. Config that is identified via the argument `--config` or environmental variable `KLEIN_CONFIG`
Configs will override any previous values as they are applied.
### Environment Aware
The module is "Environment Aware", i.e. it will look for environment variables in the first instance. If a valid variable exists then this will be used regardless of any config that may have been supplied.
The path is transformed by converting the string to uppercase and replacing all dots with underscores.
```
my.config.setting => MY_CONFIG_SETTING
```
Sub-config items are still overriden by the same environment variables as in the root config.
## Development
This project uses [pipenv](https://github.com/pypa/pipenv). To install it, run `pip install pipenv`.
### Development
```
pipenv install --dev
```
### Testing
```bash
pipenv run python -m pytest
```
For test coverage you can run:
```bash
pipenv shell
pipenv run python -m pytest --cov-report term --cov src/ tests/
```
## Unit testing config in another library.
You need to monkey patch the config library and override what the methods do in your test code.
First create your test version of config. Let's say it is in the module `tests.test_config`.
```python
from klein_config.config import EnvironmentAwareConfig
config_dict = {
'consumer': {
'name': 'text_classifier',
'queue': 'text_classifier',
},
'mongo': {
'host': 'localhost',
'port': 27017,
'doclib_database': 'doclib',
'documents_collection': 'documents',
'text_classification_collection': 'text_classification',
}
}
config = EnvironmentAwareConfig(initial=config_dict)
def get_config():
return config
```
Then in your test code you can monkey patch the config library like this:
```python
import sys
sys.modules['klein_config'] = __import__('tests.test_config')
from tests.test_config import config
```
Now any test code that uses klein_config will use this test version of the config library.
### Troubleshooting
If you are unable to run `pipenv shell` and are having permission errors, you can spin up a virtual environment in which to run
the `pipenv` commands:
```bash
pip install virtualenv // install virtualenv module
virtual env venv // create your virtual environment (run command from project root directory)
source venv/bin/activate // start the virtual environment
pipenv install --dev // install dependencies - you should now be able to run the tests with the above commands
```
### Known issue
#### Library does not install on some python versions.
This issue has appeared on a few occasions due to a tagged dependency on pyyaml. This library requires certain version of python to install.
If this library does not install on pyyaml failure, you can still install and use this library with using --no-deps flag and manually install the dependencies.
```
pip install --no-deps klein_config # Don't forget to install the dependencies as needed
```
### License
This project is licensed under the terms of the Apache 2 license, which can be found in the repository as `LICENSE.txt`
Raw data
{
"_id": null,
"home_page": "https://github.com/mdcatapult/py-config",
"name": "klein-config",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Matthew Cockayne, Mark Laing, Gemma Holliday, Roman Ma",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/7a/0f/8ce2119b9088da5e431e901db734b434c4117d6d5d5aa8b12d2d42b720d5/klein_config-4.0.2.tar.gz",
"platform": null,
"description": "# Klein Config\n\nModule to provide config management\n\n## Usage\n\n```python\nfrom klein_config import get_config\n\n# Can be overriden with env variable MY_CONFIG_SETTING\nconfig = get_config({\"my\": {\"config\": {\"setting\": \"initialised value\"}})\n\n# Access via `get` accessor with no backup (raises ConfigMissingException if not found).\nvalue = config.get(\"my.config.setting\")\n\n# Access via `get` accessor method with a backup.\nbackup_value = config.get(\"not.a.setting\", \"backup value\")\n\n# Access via `dict` (raises KeyError if not found).\nsame_value = config[\"my.config.setting\"]\n\n# Sub-configs are created if the value is another `dict`.\nintermediate_config = config[\"my.config\"]\nsame_value_again = intermediate_config[\"setting\"]\n```\n\n### Structure\nInternally the config object uses the ConfigTree structure that is part of pyhocon. This can be traversed easily with the get method using dot notation as outlined above.\n\n### Config Initialisation\nThe `get_config` function looks for :\n- argument `--common` or environmental variable `KLEIN_COMMON` to specify a valid filepath for a common config file (in either JSON or YAML format); and\n- argument `--config` or environmental variable `KLEIN_CONFIG` to specify a valid filepath for a config file \n\n\nN.B. Passing both environmental variables _and_ arguments for either config or common is ambiguous and is therefore NOT accepted.\n\nYou can also pass a `dict` into the `get_config` function.\n\n#### Example configs\nJSON:\n```json\n{\n \"rabbitmq\": {\n \"host\": [\n \"localhost\"\n ],\n \"port\": 5672,\n \"username\": \"username\",\n \"password\": \"password\"\n },\n \"mongo\": {\n \"host\": [\n \"mongo.domain.com\"\n ],\n \"username\": \"username\",\n \"password\": \"password\"\n }\n}\n```\nYAML:\n```yaml\nmongo:\n host:\n - mongo.domain.com\n password: password\n username: username\nrabbitmq:\n host:\n - localhost\n password: username\n port: 5672\n username: password\n```\n\nExample config files are also provided in [json](example.config.json) and [yaml](example.config.yaml) formats.\n\n### Order precedence\nThe configs are applied to the config object in the following order: \n\n1. Common config as identified via argument `--common` or environmental variable `KLEIN_COMMON`\n2. Config that is injected via the Class constructor\n3. Config that is identified via the argument `--config` or environmental variable `KLEIN_CONFIG`\n\n\nConfigs will override any previous values as they are applied.\n\n### Environment Aware\nThe module is \"Environment Aware\", i.e. it will look for environment variables in the first instance. If a valid variable exists then this will be used regardless of any config that may have been supplied.\n\nThe path is transformed by converting the string to uppercase and replacing all dots with underscores.\n\n```\nmy.config.setting => MY_CONFIG_SETTING\n```\n\nSub-config items are still overriden by the same environment variables as in the root config.\n\n## Development\nThis project uses [pipenv](https://github.com/pypa/pipenv). To install it, run `pip install pipenv`.\n\n### Development\n```\npipenv install --dev\n```\n\n### Testing\n```bash\npipenv run python -m pytest\n```\nFor test coverage you can run:\n```bash\npipenv shell\npipenv run python -m pytest --cov-report term --cov src/ tests/\n```\n\n## Unit testing config in another library.\nYou need to monkey patch the config library and override what the methods do in your test code.\nFirst create your test version of config. Let's say it is in the module `tests.test_config`.\n\n```python\nfrom klein_config.config import EnvironmentAwareConfig\n\nconfig_dict = {\n 'consumer': {\n 'name': 'text_classifier',\n 'queue': 'text_classifier',\n },\n 'mongo': {\n 'host': 'localhost',\n 'port': 27017,\n 'doclib_database': 'doclib',\n 'documents_collection': 'documents',\n 'text_classification_collection': 'text_classification',\n }\n}\n\nconfig = EnvironmentAwareConfig(initial=config_dict)\n\ndef get_config():\n return config\n\n```\nThen in your test code you can monkey patch the config library like this:\n\n```python\nimport sys\nsys.modules['klein_config'] = __import__('tests.test_config')\n\nfrom tests.test_config import config\n```\nNow any test code that uses klein_config will use this test version of the config library.\n\n### Troubleshooting\n\nIf you are unable to run `pipenv shell` and are having permission errors, you can spin up a virtual environment in which to run \nthe `pipenv` commands:\n\n```bash\npip install virtualenv // install virtualenv module\nvirtual env venv // create your virtual environment (run command from project root directory)\nsource venv/bin/activate // start the virtual environment\npipenv install --dev // install dependencies - you should now be able to run the tests with the above commands\n```\n\n### Known issue\n\n#### Library does not install on some python versions.\nThis issue has appeared on a few occasions due to a tagged dependency on pyyaml. This library requires certain version of python to install. \n\nIf this library does not install on pyyaml failure, you can still install and use this library with using --no-deps flag and manually install the dependencies. \n\n```\npip install --no-deps klein_config # Don't forget to install the dependencies as needed\n```\n\n\n### License\nThis project is licensed under the terms of the Apache 2 license, which can be found in the repository as `LICENSE.txt`\n",
"bugtrack_url": null,
"license": "Apache V2",
"summary": "Read and manage config from environment variables and files",
"version": "4.0.2",
"project_urls": {
"Homepage": "https://github.com/mdcatapult/py-config"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d053c7c042ef825e7ef6c81d73845860b2c91349b5bf6436227591de6095191",
"md5": "b09dfe242285fce6deaa093962be5c5f",
"sha256": "4805d4a86a810c046ccd2b54ad2c86780a7cfa36b05abfbd37aae1b05c457f3c"
},
"downloads": -1,
"filename": "klein_config-4.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b09dfe242285fce6deaa093962be5c5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9081,
"upload_time": "2024-02-14T16:38:20",
"upload_time_iso_8601": "2024-02-14T16:38:20.463666Z",
"url": "https://files.pythonhosted.org/packages/9d/05/3c7c042ef825e7ef6c81d73845860b2c91349b5bf6436227591de6095191/klein_config-4.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a0f8ce2119b9088da5e431e901db734b434c4117d6d5d5aa8b12d2d42b720d5",
"md5": "af96474f3b2fe0c9b6847da57d93d6dd",
"sha256": "5cef8622b8679936bc71a2dd463da2e295fbb82e929ca68e37d7fb48a5a84e2d"
},
"downloads": -1,
"filename": "klein_config-4.0.2.tar.gz",
"has_sig": false,
"md5_digest": "af96474f3b2fe0c9b6847da57d93d6dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8672,
"upload_time": "2024-02-14T16:38:21",
"upload_time_iso_8601": "2024-02-14T16:38:21.608488Z",
"url": "https://files.pythonhosted.org/packages/7a/0f/8ce2119b9088da5e431e901db734b434c4117d6d5d5aa8b12d2d42b720d5/klein_config-4.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 16:38:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdcatapult",
"github_project": "py-config",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "klein-config"
}
JSON
