envTOML

envTOML is an answer to a fairly simple problem: including values from environment variables in TOML configuration files. In this way, it is very similar to both envyaml and varyaml which provide very similar functionality for YAML and which greatly inspired this small package.

Under the hood it uses the standard library tomllib (and tomli as a fallback for Python < 3.11).

Supports Python 3.10+.

Example

Suppose we have the following configuration saved in config.toml

[db]
host = "$DB_HOST"
port = "$DB_PORT"
username = "$DB_USERNAME"
password = "$DB_PASSWORD"
name = "my_database"

with the environment variables being set to the following

DB_HOST=some-host.tld
DB_PORT=3306
DB_USERNAME=user01
DB_PASSWORD=veryToughPas$w0rd

this config can then be parsed with envTOML in the following way:

import envtoml

cfg = envtoml.load(open('./config.toml', 'rb'))

print(cfg)
# {'db': {'host': 'some-host.tld',
#   'port': 3306,
#   'username': 'user01',
#   'password': 'veryToughPas$w0rd',
#   'name': 'my_database'}}

You can reference multiple environment variables inside a single string:

cfg = envtoml.loads(
    "db_url = 'mysql://$DB_USERNAME:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME'\\n"
)

print(cfg)
# {'db_url': 'mysql://user01:[email protected]:3306/my_database'}

Default values can be specified with ${VAR:-default}:

cfg = envtoml.loads("region = '${AWS_REGION:-us-east-1}'\\n")
# {'region': 'us-east-1'}

Literal dollar signs can be escaped with $$:

cfg = envtoml.loads("price = '$$19.99'\\n")
# {'price': '$19.99'}

Lists are supported too:

cfg = envtoml.loads("scopes = ['$SCOPE_A', '$SCOPE_B']\\n")

To fail when a referenced env var is missing, pass fail_on_missing=True. This raises ValueError when a variable is not present or is empty:

# Example: fail fast if API_TOKEN is not set.
cfg = envtoml.loads("api_token = '$API_TOKEN'\\n", fail_on_missing=True)
# Raises ValueError: API_TOKEN not found in environment

Tests

This project uses uv. After installing it, run the following from the project's root directory:

uv sync --group dev
uv run pytest

For coverage:

uv run pytest --cov=envtoml

License

Licensed under the MIT license (see LICENSE file for more details).