envilder 0.1.0__py3-none-any.whl

envilder/__init__.py

@@ -0,0 +1,29 @@
+from envilder.application.envilder_client import EnvilderClient
+from envilder.application.map_file_parser import MapFileParser
+from envilder.domain.envilder_options import EnvilderOptions
+from envilder.domain.map_file_config import MapFileConfig
+from envilder.domain.parsed_map_file import ParsedMapFile
+from envilder.domain.ports.secret_provider import ISecretProvider
+from envilder.domain.secret_provider_type import SecretProviderType
+from envilder.infrastructure.aws.aws_ssm_secret_provider import (
+    AwsSsmSecretProvider,
+)
+from envilder.infrastructure.azure.azure_key_vault_secret_provider import (
+    AzureKeyVaultSecretProvider,
+)
+from envilder.infrastructure.secret_provider_factory import (
+    SecretProviderFactory,
+)
+
+__all__ = [
+    "AwsSsmSecretProvider",
+    "AzureKeyVaultSecretProvider",
+    "EnvilderClient",
+    "EnvilderOptions",
+    "ISecretProvider",
+    "MapFileConfig",
+    "MapFileParser",
+    "ParsedMapFile",
+    "SecretProviderFactory",
+    "SecretProviderType",
+]

envilder/application/__init__.py

@@ -0,0 +1,7 @@
+from envilder.application.envilder_client import EnvilderClient
+from envilder.application.map_file_parser import MapFileParser
+
+__all__ = [
+    "EnvilderClient",
+    "MapFileParser",
+]

envilder/application/envilder_client.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import os
+
+from envilder.domain.parsed_map_file import ParsedMapFile
+from envilder.domain.ports.secret_provider import ISecretProvider
+
+
+class EnvilderClient:
+    def __init__(self, secret_provider: ISecretProvider) -> None:
+        if secret_provider is None:
+            raise ValueError("secret_provider cannot be None")
+        self._secret_provider = secret_provider
+
+    def resolve_secrets(self, map_file: ParsedMapFile) -> dict[str, str]:
+        result: dict[str, str] = {}
+
+        for env_var_name, secret_path in map_file.mappings.items():
+            secret_value = self._secret_provider.get_secret(secret_path)
+            if secret_value is not None:
+                result[env_var_name] = secret_value
+
+        return result
+
+    @staticmethod
+    def inject_into_environment(secrets: dict[str, str]) -> None:
+        for key, value in secrets.items():
+            os.environ[key] = value

envilder/application/map_file_parser.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+
+from envilder.domain.map_file_config import MapFileConfig
+from envilder.domain.parsed_map_file import ParsedMapFile
+from envilder.domain.secret_provider_type import SecretProviderType
+
+_CONFIG_KEY = "$config"
+
+_PROVIDER_MAP = {
+    "aws": SecretProviderType.AWS,
+    "azure": SecretProviderType.AZURE,
+}
+
+
+class MapFileParser:
+    def parse(self, json_content: str) -> ParsedMapFile:
+        document = json.loads(json_content)
+
+        if not isinstance(document, dict):
+            raise ValueError("Map file must be a JSON object.")
+
+        mappings: dict[str, str] = {}
+        config = MapFileConfig()
+
+        for key, value in document.items():
+            if key == _CONFIG_KEY:
+                if isinstance(value, dict):
+                    config = _deserialize_config(value)
+                continue
+
+            if isinstance(value, str):
+                mappings[key] = value
+
+        return ParsedMapFile(config=config, mappings=mappings)
+
+
+def _deserialize_config(raw: dict[str, object]) -> MapFileConfig:
+    provider_raw = raw.get("provider")
+    provider = None
+    if provider_raw is not None:
+        if not isinstance(provider_raw, str):
+            raise ValueError("Provider must be a string.")
+        normalized = provider_raw.strip().lower()
+        provider = _PROVIDER_MAP.get(normalized)
+        if provider is None:
+            raise ValueError(
+                f"Unsupported provider '{provider_raw}'."
+                " Expected one of: aws, azure."
+            )
+
+    vault_url = raw.get("vaultUrl")
+    profile = raw.get("profile")
+
+    return MapFileConfig(
+        provider=provider,
+        vault_url=vault_url if isinstance(vault_url, str) else None,
+        profile=profile if isinstance(profile, str) else None,
+    )

envilder/domain/__init__.py

@@ -0,0 +1,13 @@
+from envilder.domain.envilder_options import EnvilderOptions
+from envilder.domain.map_file_config import MapFileConfig
+from envilder.domain.parsed_map_file import ParsedMapFile
+from envilder.domain.ports.secret_provider import ISecretProvider
+from envilder.domain.secret_provider_type import SecretProviderType
+
+__all__ = [
+    "EnvilderOptions",
+    "ISecretProvider",
+    "MapFileConfig",
+    "ParsedMapFile",
+    "SecretProviderType",
+]

envilder/domain/envilder_options.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from envilder.domain.secret_provider_type import SecretProviderType
+
+
+@dataclass
+class EnvilderOptions:
+    provider: SecretProviderType | None = field(default=None)
+    vault_url: str | None = field(default=None)
+    profile: str | None = field(default=None)

envilder/domain/map_file_config.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from envilder.domain.secret_provider_type import SecretProviderType
+
+
+@dataclass
+class MapFileConfig:
+    provider: SecretProviderType | None = field(default=None)
+    vault_url: str | None = field(default=None)
+    profile: str | None = field(default=None)

envilder/domain/parsed_map_file.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from envilder.domain.map_file_config import MapFileConfig
+
+
+@dataclass
+class ParsedMapFile:
+    config: MapFileConfig
+    mappings: dict[str, str]

envilder/domain/ports/__init__.py

@@ -0,0 +1,5 @@
+from envilder.domain.ports.secret_provider import ISecretProvider
+
+__all__ = [
+    "ISecretProvider",
+]

envilder/domain/ports/secret_provider.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ISecretProvider(Protocol):
+    def get_secret(self, name: str) -> str | None: ...

envilder/domain/secret_provider_type.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class SecretProviderType(str, Enum):
+    AWS = "aws"
+    AZURE = "azure"

envilder/infrastructure/__init__.py

@@ -0,0 +1,15 @@
+from envilder.infrastructure.aws.aws_ssm_secret_provider import (
+    AwsSsmSecretProvider,
+)
+from envilder.infrastructure.azure.azure_key_vault_secret_provider import (
+    AzureKeyVaultSecretProvider,
+)
+from envilder.infrastructure.secret_provider_factory import (
+    SecretProviderFactory,
+)
+
+__all__ = [
+    "AwsSsmSecretProvider",
+    "AzureKeyVaultSecretProvider",
+    "SecretProviderFactory",
+]

envilder/infrastructure/aws/__init__.py

@@ -0,0 +1,5 @@
+from envilder.infrastructure.aws.aws_ssm_secret_provider import (
+    AwsSsmSecretProvider,
+)
+
+__all__ = ["AwsSsmSecretProvider"]

envilder/infrastructure/aws/aws_ssm_secret_provider.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from botocore.exceptions import ClientError
+from mypy_boto3_ssm import SSMClient
+
+from envilder.domain.ports.secret_provider import ISecretProvider
+
+
+class AwsSsmSecretProvider(ISecretProvider):
+    def __init__(self, ssm_client: SSMClient) -> None:
+        if ssm_client is None:
+            raise ValueError("ssm_client cannot be None")
+        self._ssm_client = ssm_client
+
+    def get_secret(self, name: str) -> str | None:
+        if not name or not name.strip():
+            raise ValueError("Secret name cannot be null or whitespace.")
+
+        try:
+            response = self._ssm_client.get_parameter(
+                Name=name, WithDecryption=True
+            )
+            param = response.get("Parameter")
+            value = param.get("Value") if param else None
+            return str(value) if value is not None else None
+        except ClientError as e:
+            error = e.response.get("Error", {})
+            if error.get("Code") == "ParameterNotFound":
+                return None
+            raise

envilder/infrastructure/azure/__init__.py

@@ -0,0 +1,5 @@
+from envilder.infrastructure.azure.azure_key_vault_secret_provider import (
+    AzureKeyVaultSecretProvider,
+)
+
+__all__ = ["AzureKeyVaultSecretProvider"]

envilder/infrastructure/azure/azure_key_vault_secret_provider.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from azure.core.exceptions import ResourceNotFoundError
+from azure.keyvault.secrets import SecretClient
+
+from envilder.domain.ports.secret_provider import ISecretProvider
+
+
+class AzureKeyVaultSecretProvider(ISecretProvider):
+    def __init__(self, secret_client: SecretClient) -> None:
+        if secret_client is None:
+            raise ValueError("secret_client cannot be None")
+        self._secret_client = secret_client
+
+    def get_secret(self, name: str) -> str | None:
+        if not name or not name.strip():
+            raise ValueError("Secret name cannot be null or empty.")
+
+        try:
+            response = self._secret_client.get_secret(name)
+            value: str | None = response.value
+            return value
+        except ResourceNotFoundError:
+            return None

envilder/infrastructure/secret_provider_factory.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+
+import boto3
+from azure.identity import DefaultAzureCredential
+from azure.keyvault.secrets import SecretClient
+
+from envilder.domain.envilder_options import EnvilderOptions
+from envilder.domain.map_file_config import MapFileConfig
+from envilder.domain.ports.secret_provider import ISecretProvider
+from envilder.domain.secret_provider_type import SecretProviderType
+from envilder.infrastructure.aws.aws_ssm_secret_provider import (
+    AwsSsmSecretProvider,
+)
+from envilder.infrastructure.azure.azure_key_vault_secret_provider import (
+    AzureKeyVaultSecretProvider,
+)
+
+
+class SecretProviderFactory:
+    @staticmethod
+    def create(
+        config: MapFileConfig,
+        options: EnvilderOptions | None = None,
+    ) -> ISecretProvider:
+        if config is None:
+            raise ValueError("config cannot be None")
+
+        provider = (
+            options.provider
+            if options and options.provider
+            else config.provider
+        )
+
+        match provider:
+            case SecretProviderType.AZURE:
+                return _create_azure_provider(config, options)
+            case SecretProviderType.AWS | None:
+                return _create_aws_provider(config, options)
+            case _:
+                raise ValueError(f"Unsupported secret provider: {provider!r}")
+
+
+def _create_azure_provider(
+    config: MapFileConfig, options: EnvilderOptions | None
+) -> AzureKeyVaultSecretProvider:
+    vault_url = (
+        options.vault_url
+        if options and options.vault_url
+        else config.vault_url
+    )
+
+    if not vault_url or not vault_url.strip():
+        raise ValueError(
+            "Vault URL must be provided for Azure Key Vault" " provider."
+        )
+
+    credential = DefaultAzureCredential()
+    secret_client = SecretClient(vault_url=vault_url, credential=credential)
+    return AzureKeyVaultSecretProvider(secret_client)
+
+
+def _create_aws_provider(
+    config: MapFileConfig, options: EnvilderOptions | None
+) -> AwsSsmSecretProvider:
+    profile = (
+        options.profile if options and options.profile else config.profile
+    )
+
+    if profile:
+        try:
+            region = _resolve_region_from_env()
+            session = (
+                boto3.Session(profile_name=profile, region_name=region)
+                if region
+                else boto3.Session(profile_name=profile)
+            )
+            ssm_client = session.client("ssm")
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create AWS session with profile"
+                f" '{profile}': {e}"
+            ) from e
+    else:
+        region = _resolve_region_from_env()
+        session = (
+            boto3.Session(region_name=region) if region else boto3.Session()
+        )
+        ssm_client = session.client("ssm")
+
+    return AwsSsmSecretProvider(ssm_client)
+
+
+def _resolve_region_from_env() -> str | None:
+    return os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")

envilder-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: envilder
+Version: 0.1.0
+Summary: Securely load environment variables from AWS SSM Parameter Store or Azure Key Vault.
+Project-URL: Homepage, https://github.com/macalbert/envilder
+Project-URL: Repository, https://github.com/macalbert/envilder
+Project-URL: Documentation, https://github.com/macalbert/envilder/tree/main/src/sdks/python
+Project-URL: Issues, https://github.com/macalbert/envilder/issues
+Author: macalbert
+License: MIT
+Keywords: aws,azure,envilder,environment,keyvault,secrets,ssm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: azure-identity>=1.14
+Requires-Dist: azure-keyvault-secrets>=4.7
+Requires-Dist: boto3>=1.26
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: boto3-stubs[ssm]>=1.26; extra == 'dev'
+Requires-Dist: isort>=5.13; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: requests>=2.31; extra == 'dev'
+Requires-Dist: testcontainers[localstack]>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/macalbert/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
+
+```bash
+pip install envilder
+```
+
+## Quick Start
+
+### Direct usage
+
+```python
+from envilder import (
+    EnvilderClient,
+    MapFileParser,
+    SecretProviderFactory,
+)
+
+json_content = open('secrets-map.json').read()
+map_file = MapFileParser().parse(json_content)
+provider = SecretProviderFactory.create(map_file.config)
+client = EnvilderClient(provider)
+secrets = client.resolve_secrets(map_file)
+
+print(secrets['DB_PASSWORD'])
+```
+
+### Inject into environment
+
+```python
+EnvilderClient.inject_into_environment(secrets)
+
+import os
+print(os.environ['DB_PASSWORD'])
+```
+
+### With runtime overrides (EnvilderOptions)
+
+Override the map file's `$config` at runtime — useful for switching providers per environment:
+
+```python
+from envilder import EnvilderOptions, SecretProviderType
+
+options = EnvilderOptions(
+    provider=SecretProviderType.AZURE,
+    vault_url='https://my-vault.vault.azure.net',
+)
+provider = SecretProviderFactory.create(map_file.config, options)
+```
+
+## Map File Format
+
+```json
+{
+  "$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`:
+
+```json
+{
+  "$config": {
+    "provider": "azure",
+    "vaultUrl": "https://my-vault.vault.azure.net"
+  },
+  "DB_PASSWORD": "db-password",
+  "API_KEY": "api-key"
+}
+```
+
+## License
+
+MIT
+
+## Development
+
+### Setup
+
+```bash
+# From the repo root
+make install-sdk-python
+```
+
+### Quality checks
+
+```bash
+make check-sdk-python    # black + isort + mypy (no changes)
+make format-sdk-python   # auto-format
+```
+
+### Running tests
+
+Unit tests run without any external dependencies:
+
+```bash
+cd tests/sdks/python
+python -m pytest -v -m "not acceptance"
+```
+
+Acceptance tests require **Docker** and a **LocalStack auth token**:
+
+```bash
+export LOCALSTACK_AUTH_TOKEN=<your-token>
+cd tests/sdks/python
+python -m pytest -v -m acceptance
+```
+
+All tests:
+
+```bash
+make test-sdk-python
+```

envilder-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+envilder/__init__.py,sha256=FYL3mKC-Eo--xTdtscDz969_2K-31RS8IjTa6USTEXc,998
+envilder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envilder/application/__init__.py,sha256=9qHF5WPYPHkVNI3aI0_P00IhGRgq8SFy_A_VDVip6wA,185
+envilder/application/envilder_client.py,sha256=SuCtF6ffoFWYl-YpmQs7giD6e5QzVFZlZCYCBdxmnSk,941
+envilder/application/map_file_parser.py,sha256=dhFGrlP8ftB5D3c9blwGCkRKLjsI0YSgoJ7NEHYwqd4,1809
+envilder/domain/__init__.py,sha256=CDNs7nHin6FbYlm5nYcbdP3PuZOoKWMjUF4WtSEXLjM,440
+envilder/domain/envilder_options.py,sha256=Glul_NZlyooOu9RFQWgleHWQajBLy5z-bZ4kKKUDzPw,338
+envilder/domain/map_file_config.py,sha256=rBUGyUZgPLI3HF-NP2k6ZMhfGAfQ46WctPHHfEjoPWU,336
+envilder/domain/parsed_map_file.py,sha256=bKcbTUOPZk1ptZY_e5VL3C-_kkuT2aQLjae7P3bvDA8,218
+envilder/domain/secret_provider_type.py,sha256=CjCD36Cv0RazWbbP8I3mBrKcX5TlmSHWwEeGnpA1eyM,97
+envilder/domain/ports/__init__.py,sha256=fbMM9haUZu49JBBBTYkRmu4eRO8xsjOiPOxqVbO1SBU,104
+envilder/domain/ports/secret_provider.py,sha256=wCoSVZOp7tSD4KEoUOMxEXkE3z9gZ5anynVaKWbXREw,154
+envilder/infrastructure/__init__.py,sha256=v9lKtr0qRrdmSPAKa0edcLq_M1ObZZr5aH5fJDqY4BA,403
+envilder/infrastructure/secret_provider_factory.py,sha256=_FbXa2X-JcdipL8gnweQuJq6IoxgVBJHS2SUNjCjxks,3007
+envilder/infrastructure/aws/__init__.py,sha256=P8aZbG2x5d-qqcUKBFFoXFiQNAD3DNtWhRkrjVS67WQ,130
+envilder/infrastructure/aws/aws_ssm_secret_provider.py,sha256=T1Zmpet3Y2ulnaqPHe11t-MtcHPA0aJgBe4TBddoLgM,1059
+envilder/infrastructure/azure/__init__.py,sha256=GDtqMa_NYMbA9TESaAnq-HfPpr5ggLZoYC7oxiBhv4g,154
+envilder/infrastructure/azure/azure_key_vault_secret_provider.py,sha256=xZcY6raehOIeQVRt7_5b28PTJFT4EnZ6nyBeDvtFo2E,831
+envilder-0.1.0.dist-info/METADATA,sha256=mFZkgvJMizFt74rPlWJUBTH6rwS9PQBZontciWmJ-Qk,3980
+envilder-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+envilder-0.1.0.dist-info/RECORD,,

envilder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any