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, aKeyError
will be raised
- replaced with the value of the
${VAR:default}
- replaced with the value of the
VAR
environment variable - if
VAR
is unset during interpolation, the default value will be used instead
- replaced with the value of the
${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
- performs list expansion on the value of the
${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
- strips whitespace from the value of the
${VAR?}
- replaced with the value of the
VAR
environment variable - if
VAR
is unset during interpolation, it will be replaced with Python'sNone
instead - this operator cannot be applied to patterns within a longer string
- replaced with the value of the
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
1d421b4e3342df6ea094119728ad03f89aff06b75b813db37a6726ca63e702fc
|
|
MD5 |
3d794f1c76272c35a73c075af1202d87
|
|
BLAKE2b-256 |
f359d236c71e2c4f9c43735f973638c43936658d9139115896316f6b6d300fbc
|
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
0deaf3cccefbf55a4a2184bdcf5806fedb8b9343ba19641393f31dfd6fe2e78e
|
|
MD5 |
ba21e6e7b03674edb0750df0837e4e77
|
|
BLAKE2b-256 |
19eb2a56b42535249452642199adb4c683c3332658762a15dd2e54772f63dfcb
|