Skip to main content

Parse YAML, JSON, and TOML into Python objects with smart environment variable interpolation.

Project description

Overview

Confspec is a configuration loading library for Python that supports smart environment variable interpolation at runtime.

It provides a simple way to load configuration from common formats like YAML, JSON, and TOML, while being easy to add support for any additional formats. Out-of-the-box, confspec supports parsing application configuration into Pydantic models, or Msgspec Structs.

The environment variable interpolation syntax allows you to keep your defaults in the configuration file, while still being able to override them from a deployment environment.

Installation

Confspec is available on PyPI and can be installed using your package manager of choice.

pip install confspec
uv add confspec

Usage

config.toml

[server]
port = "${PORT:8080}"
debug = "${DEBUG:false}"

[database]
url = "postgres://${DB_URL:postgres:postgres@localhost:5432}/postgres"

[logging]
level = "${LOG_LEVEL~:INFO}"
handlers = "${LOG_HANDLERS[,]:console,file}"

[features]
enabled = "${FEATURE_FLAGS[,]:auth,metrics,caching}"

The above configuration file can easily be loaded, with any environment substitution happening automatically.

>>> import confspec
>>> confspec.load("config.toml")
{
    "server": {
        "port": "8080",
        "debug": "false"
    },
    "database": {
        "url": "postgres://postgres:postgres@localhost:5432/postgres"
    },
    "logging": {
        "level": "INFO",
        "handlers": ["console", "file"]
    },
    "features": {
        "enabled": ["auth", "metrics", "caching"]
    }
}

Or if you wanted it to be loaded into a msgspec Struct object. Note that msgspec will coerce some fields into the requested types automatically, unless you pass strict=True.

>>> import confspec
>>> import msgspec

>>> class Server(msgspec.Struct):
...    port: int
...    debug: bool

>>> class Database(msgspec.Struct):
...    url: str

>>> class Logging(msgspec.Struct):
...    level: str
...    handlers: list[str]

>>> class Features(msgspec.Struct):
...    enabled: list[str]

>>> class Config(msgspec.Struct):
...    server: Server
...    database: Database
...    logging: Logging
...    features: Features

>>> confspec.load("config.toml", cls=Config)
Config(
    server=Server(port=8080, debug=False),
    database=Database(url='postgres://postgres:postgres@localhost:5432/postgres'),
    logging=Logging(level='INFO', handlers=['console', 'file']),
    features=Features(enabled=['auth', 'metrics', 'caching'])
)

Interpolation Syntax

  • ${VAR}
    • replaced with the value of the VAR environment variable
    • if VAR is unset during interpolation, a KeyError will be raised
  • ${VAR:default}
    • replaced with the value of the VAR environment variable
    • if VAR is unset during interpolation, the default value will be used instead
  • ${VAR[,]}
    • performs list expansion on the value of the VAR environment variable, splitting on the delimiter (in this case ,)
    • the delimiter can be any combination of one or more characters, excluding ] and }
    • this operator cannot be applied to patterns within a longer string
  • ${VAR~}
    • strips whitespace from the value of the VAR environment variable (or the default if one is specified)
    • if combined with list expansion, each individual element will have its whitespace stripped
  • ${VAR?}
    • replaced with the value of the VAR environment variable
    • if VAR is unset during interpolation, it will be replaced with Python's None instead
    • this operator cannot be applied to patterns within a longer string

Most of these interpolation rules can be combined, except for a default value and the "None as default" flag.

For example:

  • ${VAR[,]~:default} - valid
  • ${VAR[,]~?} - valid
  • ${VAR[,]~?:default} - invalid

[!NOTE] The order that the flags are written is important, as the interpolation syntax is parsed using regex. You should always specify the flags in the same order as the valid expressions shown above.

Issues

If you find any bugs, issues, or unexpected behaviour while using the library, you should open an issue with details of the problem and how to reproduce if possible. Please also open an issue for any new features you would like to see added.

Contributing

Pull requests are welcome. For major changes, please open an issue/discussion first to discuss what you would like to change.

Please try to ensure that documentation is updated if you add any features accessible through the public API.

If you use this library and like it, feel free to sign up to GitHub and star the project, it is greatly appreciated and lets me know that I'm going in the right direction!

Links

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

confspec-0.0.3.tar.gz (59.9 kB view details)

Uploaded Source

Built Distribution

confspec-0.0.3-py3-none-any.whl (15.9 kB view details)

Uploaded Python 3

File details

Details for the file confspec-0.0.3.tar.gz.

File metadata

  • Download URL: confspec-0.0.3.tar.gz
  • Upload date:
  • Size: 59.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for confspec-0.0.3.tar.gz
Algorithm Hash digest
SHA256 1d421b4e3342df6ea094119728ad03f89aff06b75b813db37a6726ca63e702fc
MD5 3d794f1c76272c35a73c075af1202d87
BLAKE2b-256 f359d236c71e2c4f9c43735f973638c43936658d9139115896316f6b6d300fbc

See more details on using hashes here.

File details

Details for the file confspec-0.0.3-py3-none-any.whl.

File metadata

  • Download URL: confspec-0.0.3-py3-none-any.whl
  • Upload date:
  • Size: 15.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for confspec-0.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 0deaf3cccefbf55a4a2184bdcf5806fedb8b9343ba19641393f31dfd6fe2e78e
MD5 ba21e6e7b03674edb0750df0837e4e77
BLAKE2b-256 19eb2a56b42535249452642199adb4c683c3332658762a15dd2e54772f63dfcb

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page