envilder 0.3.0

Securely load environment variables from AWS SSM Parameter Store or Azure Key Vault.

Envilder Python SDK

Securely load environment variables from AWS SSM Parameter Store or Azure Key Vault directly into your Python application. Zero vendor lock-in — secrets stay in your cloud.

Part of the Envilder project.

Prerequisites

• Python 3.10+
• AWS provider: AWS credentials configured (CLI, environment variables, or IAM role)
• Azure provider: Azure credentials via az login, managed identity, or environment variables

Install

uv add envilder
# or
pip install envilder

Quick Start

One-liner

from envilder import Envilder

# Resolve secrets and inject into os.environ
Envilder.load('secrets-map.json')

import os
print(os.environ['DB_PASSWORD'])

Resolve without injecting

from envilder import Envilder

secrets = Envilder.resolve_file('secrets-map.json')
print(secrets['DB_PASSWORD'])

Fluent builder (with overrides)

Override the map file's $config at runtime — useful for switching providers, profiles, or vault URLs per environment:

from envilder import Envilder, SecretProviderType

# Override provider + vault URL
secrets = (
    Envilder.from_file('secrets-map.json')
    .with_provider(SecretProviderType.AZURE)
    .with_vault_url('https://my-vault.vault.azure.net')
    .resolve()
)

# Override AWS profile and inject
(
    Envilder.from_file('secrets-map.json')
    .with_profile('staging')
    .inject()
)

Environment-based loading

Route secret loading based on your current environment. Each environment maps to its own secrets file (or None to skip loading):

from envilder import Envilder
import os

env = os.getenv('APP_ENV', 'development')

# Resolve + inject into os.environ
Envilder.load(env, {
    'production': 'prod-secrets.json',
    'development': 'dev-secrets.json',
    'test': None,  # no secrets loaded
})

Resolve without injecting:

secrets = Envilder.resolve_file(env, {
    'production': 'prod-secrets.json',
    'development': 'dev-secrets.json',
    'test': None,
})

Behaviour:

• If the environment maps to a file path, secrets are loaded from that file.
• If the environment maps to None or is not in the mapping, an empty dict is returned silently — no errors, no output.
• The environment name is stripped of leading/trailing whitespace before lookup.
• Empty or whitespace-only environment names raise ValueError.

Advanced usage

For full control over parsing, provider creation, and secret resolution:

from envilder import (
    EnvilderClient,
    EnvilderOptions,
    MapFileParser,
    SecretProviderFactory,
    SecretProviderType,
)

with open('secrets-map.json', encoding='utf-8') as file:
    json_content = file.read()
map_file = MapFileParser().parse(json_content)

# Optional: override config at runtime
options = EnvilderOptions(
    provider=SecretProviderType.AZURE,
    vault_url='https://my-vault.vault.azure.net',
)
provider = SecretProviderFactory.create(map_file.config, options)

client = EnvilderClient(provider)
secrets = client.resolve_secrets(map_file)

EnvilderClient.inject_into_environment(secrets)

Map File Format

{
  "$config": {
    "provider": "aws",
    "profile": "my-profile"
  },
  "DB_PASSWORD": "/app/prod/db-password",
  "API_KEY": "/app/prod/api-key"
}

Supported providers: aws (default), azure.

For Azure, add vaultUrl:

{
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "db-password",
  "API_KEY": "api-key"
}

Links

• Changelog
• Official Website

License

MIT

Development

Setup

# From the repo root
make install-sdk-python

Quality checks

make check-sdk-python    # black + isort + mypy (no changes)
make format-sdk-python   # auto-format

Running tests

Unit tests run without any external dependencies:

cd tests/sdks/python
python -m pytest -v -m "not acceptance"

Acceptance tests require Docker and a LocalStack auth token:

export LOCALSTACK_AUTH_TOKEN=<your-token>
cd tests/sdks/python
python -m pytest -v -m acceptance

All tests:

make test-sdk-python