[](LICENSE.md)
[](https://codecov.io/gh/OpenVoiceOS/ovos-config)
[](http://makeapullrequest.com)
[](https://matrix.to/#/#OpenVoiceOS-general:matrix.org)
[](https://github.com/OpenVoiceOS/OpenVoiceOS/discussions)
# OVOS-config
helper package to interact with mycroft config
## Command Line usage
A small helper tool is included to quickly show, get or set config values
<img width="1214" alt="ovos-config" src="https://user-images.githubusercontent.com/25036977/219516755-b454f28f-2a34-4caf-a91f-6182ff68049a.png">
Quick rundown (cli):
* `ovos-config get`
* Loose search (search a key or parts therof):\
\
Given an entry of
{'PHAL': {
'ovos-PHAL-plugin-system': {
'enabled': True
},
'ovos-PHAL-plugin-connectivity-events': {
'enabled': True
},
...
}
`ovos-config get -k phal` would yield **all** PHAL entries and present it to the user (and the path where they were found)
* Strict search (search keys in a distinct location):
`ovos-config get -k /PHAL/ovos-PHAL-plugin-system/enabled`
This will output only the value or exit out if no key is found (root slash indicating a strict search)
* `ovos-config set`
* Searches loosely for keys containing the query string and presents a choice to the user to define a value
`ovos-config set -k phal`
<img width="423" alt="ovos-config2" src="https://user-images.githubusercontent.com/25036977/219526126-dfc547e7-6110-461a-92ba-83e850d03c70.png">
The type is derived from the joined config and thus can be safely cast into the user conf.\
Optionally a value (`-v`) can be sent as an argument.
* `ovos-config show`
* Get a full table of either the joined, user (`-u`), system (`-s`) or remote (`-r`) configuration.
This can be further refined by passing a `--section`, which can be listed with `ovos-config show -l`
--------------
## Configuration Structure
### ovos.conf
The `ovos_config` package determines which config files to load based on `ovos.conf`.
`get_ovos_config` will return default values that load `mycroft.conf` unless otherwise configured.
`ovos.conf` files are loaded in the following order, with later files taking priority over earlier ones in the list:
1. /etc/OpenVoiceOS/ovos.conf
2. /etc/mycroft/ovos.conf (Deprecated)
3. `XDG_CONFIG_DIRS` + /OpenVoiceOS/ovos.conf
3. /etc/xdg/OpenVoiceOS/ovos.conf
4. `XDG_CONFIG_HOME` (default ~/.config) + /OpenVoiceOS/ovos.conf
A simple `ovos_config` should have a structure like:
```json
{
"base_folder": "mycroft",
"config_filename": "mycroft.conf",
"default_config_path": "<Absolute Path to Installed Core>/configuration/mycroft.conf",
"module_overrides": {},
"submodule_mappings": {}
}
```
>*Note*: `default_config_path` should always be an absolute path. This is generally
detected automatically, but any manual override must specify an absolute path to a json or yaml config file.
Non-Mycroft modules may specify alternate config paths. A call to `get_ovos_config` from
`neon_core` or `neon_messagebus` will return a configuration like:
```json
{
"base_folder": "neon",
"config_filename": "neon.yaml",
"default_config_path": "/etc/example/config/neon.yaml",
"module_overrides": {
"neon_core": {
"base_folder": "neon",
"config_filename": "neon.yaml",
"default_config_path": "/etc/example/config/neon.yaml"
}
},
"submodule_mappings": {
"neon_core.skills.skill_manager": "neon_core",
"neon_messagebus": "neon_core",
"neon_speech": "neon_core",
"neon_audio": "neon_core",
"neon_gui": "neon_core"
}
}
```
If `get_ovos_config` was called from `mycroft` with the same configuration file as the last example,
the returned configuration would be:
```json
{
"base_folder": "mycroft",
"config_filename": "mycroft.conf",
"default_config_path": "<Path to Installed Core>/configuration/mycroft.conf",
"module_overrides": {
"neon_core": {
"base_folder": "neon",
"config_filename": "neon.yaml",
"default_config_path": "/etc/example/config/neon.yaml"
}
},
"submodule_mappings": {
"neon_core.skills.skill_manager": "neon_core",
"neon_messagebus": "neon_core",
"neon_speech": "neon_core",
"neon_audio": "neon_core",
"neon_gui": "neon_core"
}
}
```
## Configuration
`ovos_config.config.Configuration` is a singleton object that loads a single config
object. The configuration files loaded are determined by `ovos.conf` as described above.
Using the above example, if `Configuration()` is called from `neon_speech`, the
following configs would be loaded in this order:
1. /etc/example/config/neon.yaml
2. `os.environ.get('MYCROFT_SYSTEM_CONFIG')` or /etc/neon/neon.yaml
3. `os.environ.get('MYCROFT_WEB_CACHE')` or `XDG_CONFIG_PATH`/neon/web_cache.json (unless `disable_remote_config == True` in earlier config)
4. ~/.neon/neon.yaml (Deprecated)
3. `XDG_CONFIG_DIRS` + /neon/neon.yaml
3. /etc/xdg/neon/neon.yaml
4. `XDG_CONFIG_HOME` (default ~/.config) + /neon/neon.yaml
### Configuring Configuration
There are a couple of special configuration keys that change the way the configuration stack loads.
* `Default` config refers to the config specified at `default_config_path` in
`ovos.conf` (#1 `/etc/example/config/neon.yaml` in the stack above).
* `System` config refers to the config at `/etc/{base_folder}/{config_filename}` (#2 `/etc/neon/neon.yaml` in the stack above).
#### protected_keys
A `"protected_keys"` configuration section may be added to a `Default` or `System` Config file
(default `/etc/mycroft/mycroft.conf`). This configuration section specifies
other configuration keys that may not be specified in `remote` or `user` configurations.
Keys may specify nested parameters with `.` to exclude specific keys within nested dictionaries.
An example config could be:
```json
{
"protected_keys": {
"remote": [
"gui_websocket.host",
"websocket.host"
],
"user": [
"gui_websocket.host"
]
}
}
```
This example specifies that `config['gui_websocket']['host']` may be specified in user configuration, but not remote.
`config['websocket']['host']` may not be specified in user or remote config, so it will only consider default
and system configurations.
#### disable_user_config
If this config parameter is set to True in `Default` or `System` configuration,
no user configurations will be loaded (no XDG configuration paths).
#### disable_remote_config
If this config parameter is set to True in `Default` or `System` configuration,
the remote configuration (`web_cache.json`) will not be loaded.
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenVoiceOS/ovos-config",
"name": "ovos-config",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/01/96/c29668d714d7941f17d7aaff02b91f753efa2e9497b226dc49e886bcd89b/ovos-config-0.0.12.tar.gz",
"platform": null,
"description": "[](LICENSE.md) \n\n[](https://codecov.io/gh/OpenVoiceOS/ovos-config)\n[](http://makeapullrequest.com)\n[](https://matrix.to/#/#OpenVoiceOS-general:matrix.org)\n[](https://github.com/OpenVoiceOS/OpenVoiceOS/discussions)\n\n# OVOS-config\n\nhelper package to interact with mycroft config\n\n## Command Line usage\n\nA small helper tool is included to quickly show, get or set config values\n\n<img width=\"1214\" alt=\"ovos-config\" src=\"https://user-images.githubusercontent.com/25036977/219516755-b454f28f-2a34-4caf-a91f-6182ff68049a.png\">\n\nQuick rundown (cli):\n\n* `ovos-config get`\n \n * Loose search (search a key or parts therof):\\\n \\\nGiven an entry of\n\n {'PHAL': {\n 'ovos-PHAL-plugin-system': {\n 'enabled': True\n },\n 'ovos-PHAL-plugin-connectivity-events': {\n 'enabled': True\n },\n ... \n }\n\n `ovos-config get -k phal` would yield **all** PHAL entries and present it to the user (and the path where they were found)\n\n\n * Strict search (search keys in a distinct location): \n\n `ovos-config get -k /PHAL/ovos-PHAL-plugin-system/enabled` \n\n This will output only the value or exit out if no key is found (root slash indicating a strict search)\n\n* `ovos-config set` \n\n * Searches loosely for keys containing the query string and presents a choice to the user to define a value\n\n `ovos-config set -k phal`\n \n <img width=\"423\" alt=\"ovos-config2\" src=\"https://user-images.githubusercontent.com/25036977/219526126-dfc547e7-6110-461a-92ba-83e850d03c70.png\">\n\n The type is derived from the joined config and thus can be safely cast into the user conf.\\\n Optionally a value (`-v`) can be sent as an argument.\n\n* `ovos-config show` \n\n * Get a full table of either the joined, user (`-u`), system (`-s`) or remote (`-r`) configuration.\n This can be further refined by passing a `--section`, which can be listed with `ovos-config show -l`\n\n \n--------------\n \n\n## Configuration Structure\n\n### ovos.conf\nThe `ovos_config` package determines which config files to load based on `ovos.conf`.\n`get_ovos_config` will return default values that load `mycroft.conf` unless otherwise configured.\n\n`ovos.conf` files are loaded in the following order, with later files taking priority over earlier ones in the list:\n1. /etc/OpenVoiceOS/ovos.conf\n2. /etc/mycroft/ovos.conf (Deprecated)\n3. `XDG_CONFIG_DIRS` + /OpenVoiceOS/ovos.conf\n3. /etc/xdg/OpenVoiceOS/ovos.conf\n4. `XDG_CONFIG_HOME` (default ~/.config) + /OpenVoiceOS/ovos.conf\n\nA simple `ovos_config` should have a structure like:\n\n```json\n{\n\"base_folder\": \"mycroft\",\n\"config_filename\": \"mycroft.conf\",\n\"default_config_path\": \"<Absolute Path to Installed Core>/configuration/mycroft.conf\",\n\"module_overrides\": {},\n\"submodule_mappings\": {}\n}\n```\n>*Note*: `default_config_path` should always be an absolute path. This is generally\ndetected automatically, but any manual override must specify an absolute path to a json or yaml config file.\n\nNon-Mycroft modules may specify alternate config paths. A call to `get_ovos_config` from \n`neon_core` or `neon_messagebus` will return a configuration like:\n\n```json\n{\n \"base_folder\": \"neon\",\n \"config_filename\": \"neon.yaml\",\n \"default_config_path\": \"/etc/example/config/neon.yaml\",\n \"module_overrides\": {\n \"neon_core\": {\n \"base_folder\": \"neon\",\n \"config_filename\": \"neon.yaml\",\n \"default_config_path\": \"/etc/example/config/neon.yaml\"\n }\n },\n \"submodule_mappings\": {\n \"neon_core.skills.skill_manager\": \"neon_core\",\n \"neon_messagebus\": \"neon_core\",\n \"neon_speech\": \"neon_core\",\n \"neon_audio\": \"neon_core\",\n \"neon_gui\": \"neon_core\"\n }\n}\n```\n\nIf `get_ovos_config` was called from `mycroft` with the same configuration file as the last example,\nthe returned configuration would be:\n\n```json\n{\n \"base_folder\": \"mycroft\",\n \"config_filename\": \"mycroft.conf\",\n \"default_config_path\": \"<Path to Installed Core>/configuration/mycroft.conf\",\n \"module_overrides\": {\n \"neon_core\": {\n \"base_folder\": \"neon\",\n \"config_filename\": \"neon.yaml\",\n \"default_config_path\": \"/etc/example/config/neon.yaml\"\n }\n },\n \"submodule_mappings\": {\n \"neon_core.skills.skill_manager\": \"neon_core\",\n \"neon_messagebus\": \"neon_core\",\n \"neon_speech\": \"neon_core\",\n \"neon_audio\": \"neon_core\",\n \"neon_gui\": \"neon_core\"\n }\n}\n```\n\n## Configuration\n`ovos_config.config.Configuration` is a singleton object that loads a single config\nobject. The configuration files loaded are determined by `ovos.conf` as described above.\nUsing the above example, if `Configuration()` is called from `neon_speech`, the\nfollowing configs would be loaded in this order:\n\n1. /etc/example/config/neon.yaml\n2. `os.environ.get('MYCROFT_SYSTEM_CONFIG')` or /etc/neon/neon.yaml\n3. `os.environ.get('MYCROFT_WEB_CACHE')` or `XDG_CONFIG_PATH`/neon/web_cache.json (unless `disable_remote_config == True` in earlier config)\n4. ~/.neon/neon.yaml (Deprecated)\n3. `XDG_CONFIG_DIRS` + /neon/neon.yaml\n3. /etc/xdg/neon/neon.yaml\n4. `XDG_CONFIG_HOME` (default ~/.config) + /neon/neon.yaml\n\n### Configuring Configuration\nThere are a couple of special configuration keys that change the way the configuration stack loads.\n\n* `Default` config refers to the config specified at `default_config_path` in \n`ovos.conf` (#1 `/etc/example/config/neon.yaml` in the stack above).\n* `System` config refers to the config at `/etc/{base_folder}/{config_filename}` (#2 `/etc/neon/neon.yaml` in the stack above).\n\n#### protected_keys\nA `\"protected_keys\"` configuration section may be added to a `Default` or `System` Config file\n(default `/etc/mycroft/mycroft.conf`). This configuration section specifies \nother configuration keys that may not be specified in `remote` or `user` configurations.\nKeys may specify nested parameters with `.` to exclude specific keys within nested dictionaries.\nAn example config could be:\n\n```json\n{\n \"protected_keys\": {\n \"remote\": [\n \"gui_websocket.host\",\n \"websocket.host\"\n ],\n \"user\": [\n \"gui_websocket.host\"\n ]\n }\n}\n```\nThis example specifies that `config['gui_websocket']['host']` may be specified in user configuration, but not remote.\n`config['websocket']['host']` may not be specified in user or remote config, so it will only consider default\nand system configurations.\n\n#### disable_user_config\nIf this config parameter is set to True in `Default` or `System` configuration, \nno user configurations will be loaded (no XDG configuration paths).\n\n#### disable_remote_config\nIf this config parameter is set to True in `Default` or `System` configuration, \nthe remote configuration (`web_cache.json`) will not be loaded.\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "ovos-core configuration module",
"version": "0.0.12",
"project_urls": {
"Homepage": "https://github.com/OpenVoiceOS/ovos-config"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a866da2d6978a2ca396229ad47eb759b512f82295d293c8ad35d81c3d541c8d0",
"md5": "f021e7601cf6c9ece63169aaa429dce9",
"sha256": "ae7650f5802994aa83206a285411f31686954d6ea49c48bbca7640cf8856bdb7"
},
"downloads": -1,
"filename": "ovos_config-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f021e7601cf6c9ece63169aaa429dce9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32238,
"upload_time": "2023-12-28T23:56:12",
"upload_time_iso_8601": "2023-12-28T23:56:12.712755Z",
"url": "https://files.pythonhosted.org/packages/a8/66/da2d6978a2ca396229ad47eb759b512f82295d293c8ad35d81c3d541c8d0/ovos_config-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0196c29668d714d7941f17d7aaff02b91f753efa2e9497b226dc49e886bcd89b",
"md5": "dfd88d0fbe346146f124f3a3e7bfe139",
"sha256": "32cc5a5662f356749684a4cc7133545a5b41d2176fc3421a5c4e1d6210992f48"
},
"downloads": -1,
"filename": "ovos-config-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "dfd88d0fbe346146f124f3a3e7bfe139",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31240,
"upload_time": "2023-12-28T23:56:14",
"upload_time_iso_8601": "2023-12-28T23:56:14.629630Z",
"url": "https://files.pythonhosted.org/packages/01/96/c29668d714d7941f17d7aaff02b91f753efa2e9497b226dc49e886bcd89b/ovos-config-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-28 23:56:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenVoiceOS",
"github_project": "ovos-config",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ovos-config"
}
JSON
