# heare-config
Configuration library used by projects under heare.io
# Usage
heare-config allows developers to declare typed configuration using a code-as-schema syntax.
The Setting class will infer the type of the property from the default parser.
## Basic SettingsDefinition
```python3
from heare.config import SettingsDefinition, Setting
class MyConfig(SettingsDefinition):
foo = Setting(str, default="bazinga")
bar = Setting(float, default=1.0)
config: MyConfig = MyConfig.load()
config.foo.get() # "bazinga"
config.bar.get() # 1.0
```
The `MyConfig.load()` will create an instance of MyConfig with GettableConfig objects, populated accordingly.
### ListSettings
The `ListSetting` is a version of `Setting` that yields results as a list. Usage varies slightly between command line, environment variables, and config files.
```python3
from heare.config import SettingsDefinition, ListSetting, SettingAliases
class MyListConfig(SettingsDefinition):
numbers = ListSetting(int, default=[], aliases=SettingAliases(
flag='number'
))
config: MyListConfig = MyListConfig.load()
config.numbers.get() # []
```
## Default Invocation
The settings for a definition can be specified in three ways: command line flags, environment variable, and config files, with conventions matching each format to the SettingsDefinition.
By default, each setting property name is scoped by its definition class name, but will also have a short-name version for convenience, with formats relevant to the configuration source.
### Command Line Flags
Command-line flags address config by a fully qualified flag name of the format `<class name>.<property name>`,
a simple flag of the format `<property name>`, or a short flag of the form `<first char of property name>`.
```shell
# command line flags
$ ./main.py --foo FOO --bar 10.0
# fully qualified command line flag
$ ./main.py --MyConfig.foo FOO --MyConfig.bar 10.0
# command line short flags
$ ./main.py -f FOO -b 10.0
```
#### Multiple Values with ListSettings
Command-line flags can be specified multiple times. With a standard setting, the last specified flag will override any previous values. With a ListSetting, a list will be created
with order matching the command line invocation.
```shell
$ ./main.py --number 1 --number 2
# fully qualified command line flag
$ ./main.py --MyListConfig.number 1 --MyListConfig.number 2
# command line short flags
$ ./main.py -f FOO -b 10.0
```
*Note:* It is invalid to mix formats of command line flags in a single invocation. The following example will yield a runtime error.
```shell
$ ./main.py --MyListConfig.number 1 --number 2 # foo == [1, 2]
```
*Note:* As the parsers share a common utility class, it is technically possible to merge multiple ListSettings together by use of multiple csv values for a flag.
This is not considered a best practice, and may be deprecated in a future refactoring.
```shell
$ ./main.py --number 1,2,3 --number 4,5,6 # foo = [1,2,3,4,5,6]
```
### Environment Variables
Environment variables address config by converting component names to upper snake_case, and joining parts with a double underscore `__`.
```shell
# environment variables
$ MY_CONFIG__FOO="value" MY_CONFIG__BAR="10.0" ./main.py
$ FOO="value" BAR="10.0" ./main.py
```
*Note:* At this time, quotations and other escape characters are not supported.
#### Multiple Values with ListSettings
Environment Variables allow for multiple values to be specified for a single property using comma-separated values.
```shell
# environment variables
$ MY_LIST_CONFIG__NUMBERS="1,2,3" ./main.py
$ NUMBERS="1,2,3" ./main.py
```
*Note:* At this time, quotations and other escape characters are not supported.
*Note:* It is invalid to mix formats of environment variables in a single invocation. Values will be set based on [`precedence`](#Precedence).
### Config Files
Config files address config with sections for the config class name, and matching property value names within the sections. Config file mappings do not support any aliases.
```ini
[MyConfig]
foo = "value"
bar = 10.0
```
#### Multiple Values with ListSettings
Config Files allow for multiple values to be specified for a single property using comma-separated values.
*Note:* At this time, quotations and other escape characters are not supported.
#### Collisions across Multiple Configuration Files
When multiple configuration files are specified and the files contain colliding section/properties, values will match the last specified file.
## Type Enforcement
Type enforcement is handled when transforming
## <a name="Precedence"></a>Precedence
If a configuration value is specified in multiple ways, the value in SettingsDefinition classes will be determined by precedence.
There are two layers of precedence: precedence of settings sources (CLI, Environment, and Config Files), and within a settings source (when a property can be set multiple times).
### Precedence of Settings Sources
The loader will check each settings source in the following order, and stop when first discovered.
1. CLI Arguments
2. Environment Variables
3. Config Files
4. Default from Setting
### Precedence Within Settings Sources
Different settings sources will behave differently, and again differently based on the type of `Setting` being used (singleton vs list).
#### Command Line Arguments for Settings and ListSettings
A `Setting` specified via the CLI will take the last value specified at the command line.
```shell
$ ./main.py --foo bar --foo baz # MyConfig.foo == "baz"
```
A `ListSetting` specified via the CLI will collect values specified at the command line, with the notable exception that mixed formats are
[not allowed](#Collisions).
#### Environment Variables for Settings and ListSettings
Environment variables cannot contain multiple values within a single shell session. The most recent assignment of the variable specifies the value.
It is considered invalid to specify multiple forms of the same environment variable, as it is potentially ambiguous.
```shell
$ FOO="bar" MY_CONFIG__FOO="baz" ./main.py # Raises an error, for both Setting and ListSetting
```
#### Config Files for Settings and ListSettings
Config files will be merged in the order specified. When section collisions occur, the values from the last file will override individual properties within the section.
```ini
# file1.ini
[MyConfig]
foo = bar
bar = 1.0
# file2.ini
[MyConfig]
bar = 2.0
# MyConfig.foo == bar
# MyConfig.bar == 2.0
```
## Custom Aliases
The default aliases for each format can be optionally overloaded, to help when migrating existing applications.
## Example Definition
```python3
from heare.config import SettingsDefinition, Setting, SettingAliases
class MyAliasedConfig(SettingsDefinition):
bar = Setting(str, aliases=SettingAliases(
flag='BAR',
short_flag='B',
env_variable='NOTBAR'
))
config: MyAliasedConfig = MyAliasedConfig.load()
```
### Command Line Flags
```shell
$ ./main.py --MyAliasedConfig.BAR "value"
$ ./main.py --BAR "value"
$ ./main.py -B "value"
```
### Environment Variables
Environment variables address config by converting component names to upper snake_case, and joining parts with a double underscore `__`.
```shell
$ MY_CONFIG__FOO="value" ./main.py
$ FOO="value" ./main.py
$ MY_ALIASED_CONFIG__NOTBAR="value" ./main.py
$ NOTBAR="value" ./main.py
```
## Using Multiple SettingsDefinitions
It's possible to declare multiple `SettingsDefinitions` classes within a program. `SettingsDefinition.load()` can be invoked on multiple classes,
and SettingsDefinition provides a convenience mechanism for discovering all `SettingsDefinitions`.
```python
from typing import Dict
from heare.config import SettingsDefinition
all_settings:Dict[type, SettingsDefinition] = {
definition: definition.load() for definition in SettingsDefinition.discover()
}
```
### <a name="Collisions"></a>Naming Collisions with Multiple SettingsDefinitions
Property reuse is encouraged, but ambiguity is discouraged. As noted above, it is illegal to specify multiple formats of a Setting in a single invocation.
Across settings sources, precedence handles this cleanly, however within a single source there is the potential for ambiguity.
The following example demonstrates two conflicting and potentially ambiguous configurations.
```python
from heare.config import SettingsDefinition, Setting, ListSetting
class MyFirstConfig(SettingsDefinition):
foo = ListSetting(str)
class MySecondConfig(SettingsDefinition):
foo = Setting(str)
```
```shell
$ ./main.py --MyFirstConfig.foo=bar --foo=baz
```
In the above scenario, it's not clear whether the `--foo` setting should be a member of `MyFirstConfig.foo` or not. While this will more clearly fail
when `MyFirstConfig.foo` and `MySecondConfig.foo` are of different types, the ambiguity here allows for unexpected surprises. Instead, only unambiguous
invocations are allowed: where sharing is implicit and consistent, or distinct values are explicit.
```shell
$ ./main.py --foo=bar # valid!
# MyFirstConfig.foo = ["bar"]
# MySecondConfig.foo = "bar"
$ ./main.py --MyFirstConfig.foo=bar --MySecondConfig.foo=baz # valid!
# MyFirstConfig.foo = ["bar"]
# MySecondConfig.foo = "baz"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/heare-io/heare-config",
"name": "heare-config",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Sean Fitzgerald",
"author_email": "seanfitz@heare.io",
"download_url": "https://files.pythonhosted.org/packages/d8/ee/b535ff530fa87e8b45f22c8c646a943bc65036c246d36f0fd64f357b4fb8/heare_config-1.0.7.tar.gz",
"platform": null,
"description": "# heare-config\nConfiguration library used by projects under heare.io\n\n\n# Usage\nheare-config allows developers to declare typed configuration using a code-as-schema syntax.\nThe Setting class will infer the type of the property from the default parser.\n\n## Basic SettingsDefinition\n```python3\nfrom heare.config import SettingsDefinition, Setting\n\nclass MyConfig(SettingsDefinition):\n foo = Setting(str, default=\"bazinga\")\n bar = Setting(float, default=1.0)\n\nconfig: MyConfig = MyConfig.load()\nconfig.foo.get() # \"bazinga\"\nconfig.bar.get() # 1.0\n```\nThe `MyConfig.load()` will create an instance of MyConfig with GettableConfig objects, populated accordingly.\n\n### ListSettings\nThe `ListSetting` is a version of `Setting` that yields results as a list. Usage varies slightly between command line, environment variables, and config files.\n```python3\nfrom heare.config import SettingsDefinition, ListSetting, SettingAliases\n\nclass MyListConfig(SettingsDefinition):\n numbers = ListSetting(int, default=[], aliases=SettingAliases(\n flag='number'\n ))\n\nconfig: MyListConfig = MyListConfig.load()\nconfig.numbers.get() # []\n```\n\n## Default Invocation\nThe settings for a definition can be specified in three ways: command line flags, environment variable, and config files, with conventions matching each format to the SettingsDefinition.\nBy default, each setting property name is scoped by its definition class name, but will also have a short-name version for convenience, with formats relevant to the configuration source. \n\n### Command Line Flags\nCommand-line flags address config by a fully qualified flag name of the format `<class name>.<property name>`, \na simple flag of the format `<property name>`, or a short flag of the form `<first char of property name>`.\n```shell\n# command line flags\n$ ./main.py --foo FOO --bar 10.0\n\n# fully qualified command line flag\n$ ./main.py --MyConfig.foo FOO --MyConfig.bar 10.0\n\n# command line short flags\n$ ./main.py -f FOO -b 10.0\n```\n\n#### Multiple Values with ListSettings\nCommand-line flags can be specified multiple times. With a standard setting, the last specified flag will override any previous values. With a ListSetting, a list will be created\nwith order matching the command line invocation.\n```shell\n$ ./main.py --number 1 --number 2\n\n# fully qualified command line flag\n$ ./main.py --MyListConfig.number 1 --MyListConfig.number 2\n\n# command line short flags\n$ ./main.py -f FOO -b 10.0\n```\n*Note:* It is invalid to mix formats of command line flags in a single invocation. The following example will yield a runtime error.\n```shell\n$ ./main.py --MyListConfig.number 1 --number 2 # foo == [1, 2]\n```\n\n*Note:* As the parsers share a common utility class, it is technically possible to merge multiple ListSettings together by use of multiple csv values for a flag. \nThis is not considered a best practice, and may be deprecated in a future refactoring.\n```shell\n$ ./main.py --number 1,2,3 --number 4,5,6 # foo = [1,2,3,4,5,6]\n```\n\n### Environment Variables\nEnvironment variables address config by converting component names to upper snake_case, and joining parts with a double underscore `__`. \n```shell\n# environment variables\n$ MY_CONFIG__FOO=\"value\" MY_CONFIG__BAR=\"10.0\" ./main.py\n$ FOO=\"value\" BAR=\"10.0\" ./main.py\n```\n*Note:* At this time, quotations and other escape characters are not supported.\n\n#### Multiple Values with ListSettings\nEnvironment Variables allow for multiple values to be specified for a single property using comma-separated values. \n\n\n```shell\n# environment variables\n$ MY_LIST_CONFIG__NUMBERS=\"1,2,3\" ./main.py\n$ NUMBERS=\"1,2,3\" ./main.py\n```\n*Note:* At this time, quotations and other escape characters are not supported.\n\n*Note:* It is invalid to mix formats of environment variables in a single invocation. Values will be set based on [`precedence`](#Precedence).\n\n### Config Files\nConfig files address config with sections for the config class name, and matching property value names within the sections. Config file mappings do not support any aliases.\n\n```ini\n[MyConfig]\nfoo = \"value\"\nbar = 10.0\n```\n\n#### Multiple Values with ListSettings\nConfig Files allow for multiple values to be specified for a single property using comma-separated values. \n\n*Note:* At this time, quotations and other escape characters are not supported.\n\n#### Collisions across Multiple Configuration Files\nWhen multiple configuration files are specified and the files contain colliding section/properties, values will match the last specified file.\n\n## Type Enforcement\nType enforcement is handled when transforming \n\n## <a name=\"Precedence\"></a>Precedence\nIf a configuration value is specified in multiple ways, the value in SettingsDefinition classes will be determined by precedence.\nThere are two layers of precedence: precedence of settings sources (CLI, Environment, and Config Files), and within a settings source (when a property can be set multiple times).\n\n### Precedence of Settings Sources\nThe loader will check each settings source in the following order, and stop when first discovered.\n1. CLI Arguments\n2. Environment Variables\n3. Config Files\n4. Default from Setting\n\n### Precedence Within Settings Sources\nDifferent settings sources will behave differently, and again differently based on the type of `Setting` being used (singleton vs list).\n\n#### Command Line Arguments for Settings and ListSettings\nA `Setting` specified via the CLI will take the last value specified at the command line.\n```shell\n$ ./main.py --foo bar --foo baz # MyConfig.foo == \"baz\" \n```\n\nA `ListSetting` specified via the CLI will collect values specified at the command line, with the notable exception that mixed formats are \n[not allowed](#Collisions).\n\n#### Environment Variables for Settings and ListSettings\nEnvironment variables cannot contain multiple values within a single shell session. The most recent assignment of the variable specifies the value.\nIt is considered invalid to specify multiple forms of the same environment variable, as it is potentially ambiguous. \n\n```shell\n$ FOO=\"bar\" MY_CONFIG__FOO=\"baz\" ./main.py # Raises an error, for both Setting and ListSetting\n```\n\n#### Config Files for Settings and ListSettings\nConfig files will be merged in the order specified. When section collisions occur, the values from the last file will override individual properties within the section.\n```ini\n# file1.ini\n[MyConfig]\nfoo = bar\nbar = 1.0\n\n# file2.ini\n[MyConfig]\nbar = 2.0\n\n# MyConfig.foo == bar\n# MyConfig.bar == 2.0\n```\n\n## Custom Aliases\nThe default aliases for each format can be optionally overloaded, to help when migrating existing applications.\n\n## Example Definition\n```python3\nfrom heare.config import SettingsDefinition, Setting, SettingAliases\n\nclass MyAliasedConfig(SettingsDefinition):\n bar = Setting(str, aliases=SettingAliases(\n flag='BAR',\n short_flag='B',\n env_variable='NOTBAR'\n ))\n\nconfig: MyAliasedConfig = MyAliasedConfig.load()\n```\n\n### Command Line Flags\n```shell\n$ ./main.py --MyAliasedConfig.BAR \"value\"\n$ ./main.py --BAR \"value\"\n$ ./main.py -B \"value\"\n```\n\n### Environment Variables\nEnvironment variables address config by converting component names to upper snake_case, and joining parts with a double underscore `__`. \n```shell\n$ MY_CONFIG__FOO=\"value\" ./main.py\n$ FOO=\"value\" ./main.py\n\n$ MY_ALIASED_CONFIG__NOTBAR=\"value\" ./main.py\n$ NOTBAR=\"value\" ./main.py\n```\n\n## Using Multiple SettingsDefinitions\nIt's possible to declare multiple `SettingsDefinitions` classes within a program. `SettingsDefinition.load()` can be invoked on multiple classes, \nand SettingsDefinition provides a convenience mechanism for discovering all `SettingsDefinitions`.\n```python\nfrom typing import Dict\nfrom heare.config import SettingsDefinition\n\nall_settings:Dict[type, SettingsDefinition] = {\n definition: definition.load() for definition in SettingsDefinition.discover()\n}\n```\n\n### <a name=\"Collisions\"></a>Naming Collisions with Multiple SettingsDefinitions\nProperty reuse is encouraged, but ambiguity is discouraged. As noted above, it is illegal to specify multiple formats of a Setting in a single invocation.\nAcross settings sources, precedence handles this cleanly, however within a single source there is the potential for ambiguity.\n\nThe following example demonstrates two conflicting and potentially ambiguous configurations.\n\n```python\nfrom heare.config import SettingsDefinition, Setting, ListSetting\n\nclass MyFirstConfig(SettingsDefinition):\n foo = ListSetting(str)\n\nclass MySecondConfig(SettingsDefinition):\n foo = Setting(str)\n```\n```shell\n$ ./main.py --MyFirstConfig.foo=bar --foo=baz\n```\n\nIn the above scenario, it's not clear whether the `--foo` setting should be a member of `MyFirstConfig.foo` or not. While this will more clearly fail\nwhen `MyFirstConfig.foo` and `MySecondConfig.foo` are of different types, the ambiguity here allows for unexpected surprises. Instead, only unambiguous \ninvocations are allowed: where sharing is implicit and consistent, or distinct values are explicit.\n\n```shell\n$ ./main.py --foo=bar # valid!\n\n# MyFirstConfig.foo = [\"bar\"]\n# MySecondConfig.foo = \"bar\"\n\n$ ./main.py --MyFirstConfig.foo=bar --MySecondConfig.foo=baz # valid!\n# MyFirstConfig.foo = [\"bar\"]\n# MySecondConfig.foo = \"baz\"\n```\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Heare.io Configuration Utilities",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/heare-io/heare-config"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "392445c4635566a3a931657b1759637c30445968e11fd9a653bd8e136fa2cd94",
"md5": "4e97f43bd569149b189b877bc70bf09b",
"sha256": "8d73b4d3668837da9d810ab94d561cbc11b4a92751616ac8d966c9b13032cad9"
},
"downloads": -1,
"filename": "heare_config-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e97f43bd569149b189b877bc70bf09b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11059,
"upload_time": "2024-08-31T02:08:14",
"upload_time_iso_8601": "2024-08-31T02:08:14.352423Z",
"url": "https://files.pythonhosted.org/packages/39/24/45c4635566a3a931657b1759637c30445968e11fd9a653bd8e136fa2cd94/heare_config-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d8eeb535ff530fa87e8b45f22c8c646a943bc65036c246d36f0fd64f357b4fb8",
"md5": "331f5307a575542ed73bb33c81bc1a02",
"sha256": "4e98f9aa10b0363e854a710f85866646d52f0f8ae911e533641bc310b8295c34"
},
"downloads": -1,
"filename": "heare_config-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "331f5307a575542ed73bb33c81bc1a02",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14850,
"upload_time": "2024-08-31T02:08:15",
"upload_time_iso_8601": "2024-08-31T02:08:15.655979Z",
"url": "https://files.pythonhosted.org/packages/d8/ee/b535ff530fa87e8b45f22c8c646a943bc65036c246d36f0fd64f357b4fb8/heare_config-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-31 02:08:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "heare-io",
"github_project": "heare-config",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "docutils",
"specs": [
[
"==",
"0.21.2"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.2.1"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.10.0"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "nh3",
"specs": [
[
"==",
"0.2.17"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.0"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.11.1"
]
]
},
{
"name": "Pygments",
"specs": [
[
"==",
"2.18.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.2.0"
]
]
},
{
"name": "readme_renderer",
"specs": [
[
"==",
"43.0"
]
]
},
{
"name": "tomli",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.11.0"
]
]
}
],
"lcname": "heare-config"
}
JSON
