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:
- Default values specified in the Pydantic model
- System-wide configuration in /etc/appname/config.json (and yaml)
- User configuration in ~/.appname.json (and yaml)
- Additional configuration files and values provided as command line args (e.g.
-f filenameor--set value.deeper=foo) - Environment variables
- Command-line arguments
- Dictionaries passed to the load method
...and then validates the merged configuration against the Pydantic model.
Installation
Conflator is available on PyPI:
pip install conflator
Or using poetry:
poetry add conflator
Usage
- Define Your Configuration Model: Begin by defining your configuration schema using Pydantic models. Annotate your model fields with
EnvVarandCLIArgfor environment variable and command-line argument support, respectively.
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"
- Initialize Conflator: Create an instance of the Conflator class, passing your application's name and the configuration model.
from conflator import Conflator
config = Conflator(app_name="my_app", model=AppConfig).load()
- Access Configuration: Use the loaded configuration throughout your application, knowing that the configuration has been fully validated.
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
your-app -f ./config/base.yaml -f ./config/production.yaml
Nested config just works
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
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.
Metadata
Release files for conflator 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| conflator-0.1.8.tar.gz | 9.8 kB | Without provenance | Details for conflator-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| conflator-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for conflator-0.1.8-py3-none-any.whl |
Total release size: 20.6 kB
Release files / conflator-0.1.8.tar.gz
| Download URL | conflator-0.1.8.tar.gz |
|---|---|
| Size | 9.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ee8958a3eebbfeb6fafc4b0b7b77c8a97d1752fd725ca8a514046a596f26508
|
|
BLAKE2b-256 checksum How to use checksums |
cf19e8143a210b58494025803a684de9eb94998b7b8288f42f15fbee0161019c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Release files / conflator-0.1.8-py3-none-any.whl
| Download URL | conflator-0.1.8-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e621da64183bc9207b3857cebaa9cd1aee52ea6cb4aea7492aa9d9a4b4968c5
|
|
BLAKE2b-256 checksum How to use checksums |
a2aa0d6a2c96234fb5cc3d55a3f5078268ef6bc4e69d202f86b93f17b3f8d2eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.0
|
Security for conflator 0.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.