> [!WARNING]
> This project is under development and not yet feature complete or tested.
> [!WARNING]
> This project is BETA and will be experimental for the forseable future. Interfaces and functionality are likely to change, and the project itself may be scrapped. DO NOT use this software in any project/software that is operational.
Conflator is a configuration-handling library for Python. It is designed to simplify the handling of configuration from multiple sources, such as environment variables, command line arguments, and configuration files. As an application or library developer, you specify your configuration schema with a Pydantic model, and conflator will handle the rest.
Conflator loads configuration in the following order:
1. Default values specified in the Pydantic model
2. System-wide configuration in /etc/appname/config.json (and yaml)
3. User configuration in ~/.appname.json (and yaml)
4. Additional configuration files and values provided as command line args (e.g. `-f filename` or `--set value.deeper=foo`)
4. Environment variables
5. Command-line arguments
6. Dictionaries passed to the load method
...and then validates the merged configuration against the Pydantic model.
<!-- > Conflate (/kənˈfleɪt/): combine (two or more sets of information, texts, ideas, etc.) into one. -->
## Installation
Conflator is available on PyPI:
```bash
pip install conflator
```
Or using poetry:
```bash
poetry add conflator
```
## Usage
1. **Define Your Configuration Model**: Begin by defining your configuration schema using Pydantic models. Annotate your model fields with `EnvVar` and `CLIArg` for environment variable and command-line argument support, respectively.
```python
from pydantic import Field
from conflator import EnvVar, CLIArg, ConfigModel
from annotated_types import Annotated
class AppConfig(ConfigModel):
host: str = "localhost"
port: Annotated[int, EnvVar("PORT"), CLIArg("--port")] = 5432
user: Annotated[str, EnvVar("USER"), CLIArg("--user"), Field(description="Your username")] = "foo"
```
2. **Initialize Conflator**: Create an instance of the Conflator class, passing your application's name and the configuration model.
```python
from conflator import Conflator
config = Conflator(app_name="my_app", model=AppConfig).load()
```
3. **Access Configuration**: Use the loaded configuration throughout your application, knowing that the configuration has been fully validated.
```python
print(f"User: {config.user}")
```
Try setting MY_APP_USER in the environment to see the value change, or use the `--user` flag to override the value.
## Advanced Usage
### Configuration layering for different deployments
```bash
your-app -f ./config/base.yaml -f ./config/production.yaml
```
### Nested config just works
```python
from annotated_types import Annotated
from conflator import EnvVar, CLIArg, ConfigModel
class DeeperConfig(ConfigModel):
nested: Annotated[str, EnvVar("NESTED"), CLIArg("--nested")] = "default"
class Config(ConfigModel):
host: str = "localhost"
port: int = 543
deeper: DeeperConfig = DeeperConfig()
```
### Generate the JSON schema for your configuration
```bash
config = Conflator(app_name="my_app", model=AppConfig).schema() # uses pydantic's schema method behind the scenes
```
## Limitations
* CLI arguments and environment variables are defined per model type, not per model instance. This means that you cannot have different CLI arguments or environment variables for different instances of the same model. Some support for this may be added in the future.
* Including ConfigModel's from other packages, to nest their configuration with yours, is possible. However, there is no way to resolve conflicts between CLI arguments and environment variable naming between two different config schemas. Some support for this may be added in the future.
Raw data
{
"_id": null,
"home_page": "https://github.com/ecmwf/conflator/",
"name": "conflator",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.9",
"maintainer_email": "",
"keywords": "",
"author": "James Hawkes",
"author_email": "James.Hawkes@ecmwf.int",
"download_url": "https://files.pythonhosted.org/packages/9e/00/d18e000636f77fa1299f47965d728c951d150a2dc56a07f04f3cac709683/conflator-0.1.4.tar.gz",
"platform": null,
"description": "\n\n> [!WARNING]\n> This project is under development and not yet feature complete or tested.\n\n> [!WARNING]\n> This project is BETA and will be experimental for the forseable future. Interfaces and functionality are likely to change, and the project itself may be scrapped. DO NOT use this software in any project/software that is operational.\n\nConflator is a configuration-handling library for Python. It is designed to simplify the handling of configuration from multiple sources, such as environment variables, command line arguments, and configuration files. As an application or library developer, you specify your configuration schema with a Pydantic model, and conflator will handle the rest.\n\nConflator loads configuration in the following order:\n\n1. Default values specified in the Pydantic model\n2. System-wide configuration in /etc/appname/config.json (and yaml)\n3. User configuration in ~/.appname.json (and yaml)\n4. Additional configuration files and values provided as command line args (e.g. `-f filename` or `--set value.deeper=foo`)\n4. Environment variables\n5. Command-line arguments\n6. Dictionaries passed to the load method\n\n...and then validates the merged configuration against the Pydantic model.\n\n<!-- > Conflate (/k\u0259n\u02c8fle\u026at/): combine (two or more sets of information, texts, ideas, etc.) into one. -->\n\n## Installation\n\nConflator is available on PyPI:\n\n```bash\npip install conflator\n```\n\nOr using poetry:\n\n```bash\npoetry add conflator\n```\n\n## Usage\n\n1. **Define Your Configuration Model**: Begin by defining your configuration schema using Pydantic models. Annotate your model fields with `EnvVar` and `CLIArg` for environment variable and command-line argument support, respectively.\n\n```python\nfrom pydantic import Field\nfrom conflator import EnvVar, CLIArg, ConfigModel\nfrom annotated_types import Annotated\n\nclass AppConfig(ConfigModel):\n\n host: str = \"localhost\"\n port: Annotated[int, EnvVar(\"PORT\"), CLIArg(\"--port\")] = 5432\n user: Annotated[str, EnvVar(\"USER\"), CLIArg(\"--user\"), Field(description=\"Your username\")] = \"foo\"\n```\n\n2. **Initialize Conflator**: Create an instance of the Conflator class, passing your application's name and the configuration model.\n\n```python\nfrom conflator import Conflator\n\nconfig = Conflator(app_name=\"my_app\", model=AppConfig).load()\n```\n\n3. **Access Configuration**: Use the loaded configuration throughout your application, knowing that the configuration has been fully validated.\n```python\nprint(f\"User: {config.user}\")\n```\nTry setting MY_APP_USER in the environment to see the value change, or use the `--user` flag to override the value.\n\n## Advanced Usage\n\n### Configuration layering for different deployments\n\n```bash\nyour-app -f ./config/base.yaml -f ./config/production.yaml\n```\n\n### Nested config just works\n```python\nfrom annotated_types import Annotated\nfrom conflator import EnvVar, CLIArg, ConfigModel\n\nclass DeeperConfig(ConfigModel):\n nested: Annotated[str, EnvVar(\"NESTED\"), CLIArg(\"--nested\")] = \"default\"\n\nclass Config(ConfigModel):\n host: str = \"localhost\"\n port: int = 543\n deeper: DeeperConfig = DeeperConfig()\n```\n\n### Generate the JSON schema for your configuration\n```bash\nconfig = Conflator(app_name=\"my_app\", model=AppConfig).schema() # uses pydantic's schema method behind the scenes\n```\n\n## Limitations\n\n* CLI arguments and environment variables are defined per model type, not per model instance. This means that you cannot have different CLI arguments or environment variables for different instances of the same model. Some support for this may be added in the future.\n\n* Including ConfigModel's from other packages, to nest their configuration with yours, is possible. However, there is no way to resolve conflicts between CLI arguments and environment variable naming between two different config schemas. Some support for this may be added in the future.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Load small app configurations from environment variables, command line arguments and config files, according to a pydantic model.",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/ecmwf/conflator/",
"Repository": "https://github.com/ecmwf/conflator/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd4cfa1eb200173bc8c88a9ede17ffe998a00230686dadf9a618a7df935bca63",
"md5": "51f11164cad26da96e2d3ab13d936d36",
"sha256": "5e1fcba3030228edb1120318f5a5ddf770aeb180c1e09b68d2e0e949bae16b32"
},
"downloads": -1,
"filename": "conflator-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "51f11164cad26da96e2d3ab13d936d36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.9",
"size": 10690,
"upload_time": "2024-03-14T18:23:48",
"upload_time_iso_8601": "2024-03-14T18:23:48.011589Z",
"url": "https://files.pythonhosted.org/packages/dd/4c/fa1eb200173bc8c88a9ede17ffe998a00230686dadf9a618a7df935bca63/conflator-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9e00d18e000636f77fa1299f47965d728c951d150a2dc56a07f04f3cac709683",
"md5": "a35ca5b58ed628708107a84c48b72ebc",
"sha256": "c86cac7f76f407c09f76cdb0e740460b67e552423d16c68c17adef4238193802"
},
"downloads": -1,
"filename": "conflator-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "a35ca5b58ed628708107a84c48b72ebc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.9",
"size": 9887,
"upload_time": "2024-03-14T18:23:49",
"upload_time_iso_8601": "2024-03-14T18:23:49.612711Z",
"url": "https://files.pythonhosted.org/packages/9e/00/d18e000636f77fa1299f47965d728c951d150a2dc56a07f04f3cac709683/conflator-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-14 18:23:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ecmwf",
"github_project": "conflator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pydantic",
"specs": [
[
"==",
"2.6.0"
]
]
},
{
"name": "pydantic_core",
"specs": [
[
"==",
"2.16.1"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.7.0"
]
]
},
{
"name": "rich-argparse",
"specs": [
[
"==",
"1.4.0"
]
]
}
],
"tox": true,
"lcname": "conflator"
}
JSON
