Skip to main content

conflator logo

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)
  5. Environment variables
  6. Command-line arguments
  7. 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

  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.
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"
  1. 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()
  1. 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)

Source distribution for conflator 0.1.8
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)

Table of built distributions (wheels) for conflator 0.1.8
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page