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:veryToughPas$w0rd@some-host.tld: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

To substitute from a mapping other than os.environ, pass env_values. The mapping is used exclusively — variables set only in the process environment are not consulted. This pairs well with python-dotenv’s dotenv_values(), which reads a .env file without mutating the environment:

cfg = envtoml.loads("port = '$PORT'\\n", env_values={'PORT': '8080'})
# {'port': 8080}

from dotenv import dotenv_values
cfg = envtoml.loads("port = '$PORT'\\n", env_values=dotenv_values('.env'))

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).