envilder 0.2.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

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

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"
}

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