Skip to content

Public API

This section covers the main functions intended for direct use in your applications.

envresolve.api

Public API for envresolve.

EnvResolver

Manages provider registration and secret resolution.

This class encapsulates the provider registry and resolver instance, eliminating the need for module-level global variables.

Source code in src/envresolve/api.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
class EnvResolver:
    """Manages provider registration and secret resolution.

    This class encapsulates the provider registry and resolver instance,
    eliminating the need for module-level global variables.
    """

    def __init__(self) -> None:
        """Initialize an empty provider registry."""
        self._providers: dict[str, SecretProvider] = {}
        self._resolver: SecretResolver | None = None

    def _get_resolver(self) -> SecretResolver:
        """Get or create the resolver instance.

        Returns:
            SecretResolver instance configured with registered providers
        """
        if self._resolver is None:
            self._resolver = SecretResolver(self._providers)
        return self._resolver

    def register_azure_kv_provider(self) -> None:
        """Register Azure Key Vault provider for akv:// scheme.

        This method is safe to call multiple times (idempotent).

        Raises:
            ProviderRegistrationError: If azure-identity or azure-keyvault-secrets
                is not installed
        """
        try:
            # Dynamically import the provider module
            provider_module = importlib.import_module("envresolve.providers.azure_kv")
            provider_class = provider_module.AzureKVProvider
        except ImportError as e:
            # Check which dependency is missing
            missing_deps: list[str] = []
            try:
                importlib.import_module("azure.identity")
            except ImportError:
                missing_deps.append("azure-identity")

            try:
                importlib.import_module("azure.keyvault.secrets")
            except ImportError:
                missing_deps.append("azure-keyvault-secrets")

            if missing_deps:
                deps_str = ", ".join(missing_deps)
                msg = (
                    f"Azure Key Vault provider requires: {deps_str}. "
                    "Install with: pip install envresolve[azure]"
                )
            else:
                msg = f"Failed to import Azure Key Vault provider. Error: {e}"
            raise ProviderRegistrationError(msg, original_error=e) from e

        provider = provider_class()
        self._providers["akv"] = provider
        # Reset resolver to pick up new providers
        self._resolver = None

    def resolve_secret(self, uri: str) -> str:
        """Resolve a secret URI to its value.

        This function supports:
        - Variable expansion: ${VAR} and $VAR syntax using os.environ
        - Secret URI resolution: akv:// scheme
        - Idempotent resolution: Plain strings and non-target URIs pass through

        Args:
            uri: Secret URI or plain string to resolve

        Returns:
            Resolved secret value or the original string if not a secret URI

        Raises:
            URIParseError: If the URI format is invalid
            SecretResolutionError: If secret resolution fails
            VariableNotFoundError: If a referenced variable is not found
            CircularReferenceError: If a circular variable reference is detected
        """
        resolver = self._get_resolver()
        return resolver.resolve(uri)

    def resolve_with_env(self, value: str, env: dict[str, str]) -> str:
        """Expand variables and resolve secret URIs with custom environment.

        Args:
            value: Value to resolve (may contain variables or be a secret URI)
            env: Environment dict for variable expansion

        Returns:
            Resolved value
        """
        resolver = self._get_resolver()
        return resolver.resolve(value, env)

    def load_env(
        self,
        path: str | Path = ".env",
        *,
        export: bool = True,
        override: bool = False,
    ) -> dict[str, str]:
        """Load environment variables from a .env file and resolve secret URIs.

        This function:
        1. Loads variables from the .env file
        2. Expands variable references within values
        3. Resolves secret URIs (akv://) to actual secret values
        4. Optionally exports to os.environ

        Args:
            path: Path to .env file (default: ".env")
            export: If True, export resolved variables to os.environ
            override: If True, override existing os.environ variables

        Returns:
            Dictionary of resolved environment variables

        Raises:
            FileNotFoundError: If the .env file doesn't exist
            URIParseError: If a URI format is invalid
            SecretResolutionError: If secret resolution fails
            VariableNotFoundError: If a referenced variable is not found
            CircularReferenceError: If a circular variable reference is detected
        """
        # Load .env file
        env_dict = {k: v for k, v in dotenv_values(path).items() if v is not None}

        # Build complete environment (for variable expansion)
        complete_env = dict(os.environ)
        complete_env.update(env_dict)

        # Resolve each variable
        resolved: dict[str, str] = {}
        for key, value in env_dict.items():
            resolved[key] = self.resolve_with_env(value, complete_env)

        # Export to os.environ if requested
        if export:
            for key, value in resolved.items():
                if override or key not in os.environ:
                    os.environ[key] = value

        return resolved

__init__ 

__init__() -> None

Initialize an empty provider registry.

Source code in src/envresolve/api.py 
24
25
26
27
def __init__(self) -> None:
    """Initialize an empty provider registry."""
    self._providers: dict[str, SecretProvider] = {}
    self._resolver: SecretResolver | None = None

register_azure_kv_provider 

register_azure_kv_provider() -> None

Register Azure Key Vault provider for akv:// scheme.

This method is safe to call multiple times (idempotent).

Raises:

Type Description
ProviderRegistrationError

If azure-identity or azure-keyvault-secrets is not installed
Source code in src/envresolve/api.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def register_azure_kv_provider(self) -> None:
    """Register Azure Key Vault provider for akv:// scheme.

    This method is safe to call multiple times (idempotent).

    Raises:
        ProviderRegistrationError: If azure-identity or azure-keyvault-secrets
            is not installed
    """
    try:
        # Dynamically import the provider module
        provider_module = importlib.import_module("envresolve.providers.azure_kv")
        provider_class = provider_module.AzureKVProvider
    except ImportError as e:
        # Check which dependency is missing
        missing_deps: list[str] = []
        try:
            importlib.import_module("azure.identity")
        except ImportError:
            missing_deps.append("azure-identity")

        try:
            importlib.import_module("azure.keyvault.secrets")
        except ImportError:
            missing_deps.append("azure-keyvault-secrets")

        if missing_deps:
            deps_str = ", ".join(missing_deps)
            msg = (
                f"Azure Key Vault provider requires: {deps_str}. "
                "Install with: pip install envresolve[azure]"
            )
        else:
            msg = f"Failed to import Azure Key Vault provider. Error: {e}"
        raise ProviderRegistrationError(msg, original_error=e) from e

    provider = provider_class()
    self._providers["akv"] = provider
    # Reset resolver to pick up new providers
    self._resolver = None

resolve_secret 

resolve_secret(uri: str) -> str

Resolve a secret URI to its value.

This function supports: - Variable expansion: ${VAR} and $VAR syntax using os.environ - Secret URI resolution: akv:// scheme - Idempotent resolution: Plain strings and non-target URIs pass through

Parameters:

Name Type Description Default
uri str

Secret URI or plain string to resolve

 required

Returns:

Type Description
str

Resolved secret value or the original string if not a secret URI

Raises:

Type Description
URIParseError

If the URI format is invalid
SecretResolutionError

If secret resolution fails
VariableNotFoundError

If a referenced variable is not found
CircularReferenceError

If a circular variable reference is detected
Source code in src/envresolve/api.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def resolve_secret(self, uri: str) -> str:
    """Resolve a secret URI to its value.

    This function supports:
    - Variable expansion: ${VAR} and $VAR syntax using os.environ
    - Secret URI resolution: akv:// scheme
    - Idempotent resolution: Plain strings and non-target URIs pass through

    Args:
        uri: Secret URI or plain string to resolve

    Returns:
        Resolved secret value or the original string if not a secret URI

    Raises:
        URIParseError: If the URI format is invalid
        SecretResolutionError: If secret resolution fails
        VariableNotFoundError: If a referenced variable is not found
        CircularReferenceError: If a circular variable reference is detected
    """
    resolver = self._get_resolver()
    return resolver.resolve(uri)

resolve_with_env 

resolve_with_env(value: str, env: dict[str, str]) -> str

Expand variables and resolve secret URIs with custom environment.

Parameters:

Name Type Description Default
value str

Value to resolve (may contain variables or be a secret URI)

 required
env dict[str, str]

Environment dict for variable expansion

 required

Returns:

Type Description
str

Resolved value
Source code in src/envresolve/api.py 
103
104
105
106
107
108
109
110
111
112
113
114
def resolve_with_env(self, value: str, env: dict[str, str]) -> str:
    """Expand variables and resolve secret URIs with custom environment.

    Args:
        value: Value to resolve (may contain variables or be a secret URI)
        env: Environment dict for variable expansion

    Returns:
        Resolved value
    """
    resolver = self._get_resolver()
    return resolver.resolve(value, env)

load_env 

load_env(
    path: str | Path = ".env",
    *,
    export: bool = True,
    override: bool = False,
) -> dict[str, str]

Load environment variables from a .env file and resolve secret URIs.

This function: 1. Loads variables from the .env file 2. Expands variable references within values 3. Resolves secret URIs (akv://) to actual secret values 4. Optionally exports to os.environ

Parameters:

Name Type Description Default
path str | Path

Path to .env file (default: ".env")

 '.env'
export bool

If True, export resolved variables to os.environ

 True
override bool

If True, override existing os.environ variables

 False

Returns:

Type Description
dict[str, str]

Dictionary of resolved environment variables

Raises:

Type Description
FileNotFoundError

If the .env file doesn't exist
URIParseError

If a URI format is invalid
SecretResolutionError

If secret resolution fails
VariableNotFoundError

If a referenced variable is not found
CircularReferenceError

If a circular variable reference is detected
Source code in src/envresolve/api.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def load_env(
    self,
    path: str | Path = ".env",
    *,
    export: bool = True,
    override: bool = False,
) -> dict[str, str]:
    """Load environment variables from a .env file and resolve secret URIs.

    This function:
    1. Loads variables from the .env file
    2. Expands variable references within values
    3. Resolves secret URIs (akv://) to actual secret values
    4. Optionally exports to os.environ

    Args:
        path: Path to .env file (default: ".env")
        export: If True, export resolved variables to os.environ
        override: If True, override existing os.environ variables

    Returns:
        Dictionary of resolved environment variables

    Raises:
        FileNotFoundError: If the .env file doesn't exist
        URIParseError: If a URI format is invalid
        SecretResolutionError: If secret resolution fails
        VariableNotFoundError: If a referenced variable is not found
        CircularReferenceError: If a circular variable reference is detected
    """
    # Load .env file
    env_dict = {k: v for k, v in dotenv_values(path).items() if v is not None}

    # Build complete environment (for variable expansion)
    complete_env = dict(os.environ)
    complete_env.update(env_dict)

    # Resolve each variable
    resolved: dict[str, str] = {}
    for key, value in env_dict.items():
        resolved[key] = self.resolve_with_env(value, complete_env)

    # Export to os.environ if requested
    if export:
        for key, value in resolved.items():
            if override or key not in os.environ:
                os.environ[key] = value

    return resolved

register_azure_kv_provider 

register_azure_kv_provider() -> None

Register Azure Key Vault provider for akv:// scheme.

This function should be called before attempting to resolve secrets from Azure Key Vault. It is safe to call multiple times (idempotent).

Example

import envresolve envresolve.register_azure_kv_provider()

Now you can resolve secrets (requires Azure authentication)

secret = envresolve.resolve_secret("akv://my-vault/db-password")

Source code in src/envresolve/api.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
def register_azure_kv_provider() -> None:
    """Register Azure Key Vault provider for akv:// scheme.

    This function should be called before attempting to resolve secrets
    from Azure Key Vault. It is safe to call multiple times (idempotent).

    Example:
        >>> import envresolve
        >>> envresolve.register_azure_kv_provider()
        >>> # Now you can resolve secrets (requires Azure authentication)
        >>> # secret = envresolve.resolve_secret("akv://my-vault/db-password")
    """
    _default_resolver.register_azure_kv_provider()

resolve_secret 

resolve_secret(uri: str) -> str

Resolve a secret URI to its value.

This function supports: - Variable expansion: ${VAR} and $VAR syntax using os.environ - Secret URI resolution: akv:// scheme - Idempotent resolution: Plain strings and non-target URIs pass through unchanged

Parameters:

Name Type Description Default
uri str

Secret URI or plain string to resolve

 required

Returns:

Type Description
str

Resolved secret value or the original string if not a secret URI

Raises:

Type Description
URIParseError

If the URI format is invalid
SecretResolutionError

If secret resolution fails
VariableNotFoundError

If a referenced variable is not found
CircularReferenceError

If a circular variable reference is detected

Examples:

>>> import envresolve
>>> # Idempotent - plain strings pass through
>>> value = envresolve.resolve_secret("just-a-string")
>>> value
'just-a-string'
>>> # Non-target URIs pass through unchanged
>>> uri = envresolve.resolve_secret("postgres://localhost/db")
>>> uri
'postgres://localhost/db'
>>> # Secret URIs require provider registration and authentication
>>> # envresolve.register_azure_kv_provider()
>>> # secret = envresolve.resolve_secret("akv://my-vault/db-password")
Source code in src/envresolve/api.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def resolve_secret(uri: str) -> str:
    """Resolve a secret URI to its value.

    This function supports:
    - Variable expansion: ${VAR} and $VAR syntax using os.environ
    - Secret URI resolution: akv:// scheme
    - Idempotent resolution: Plain strings and non-target URIs pass through unchanged

    Args:
        uri: Secret URI or plain string to resolve

    Returns:
        Resolved secret value or the original string if not a secret URI

    Raises:
        URIParseError: If the URI format is invalid
        SecretResolutionError: If secret resolution fails
        VariableNotFoundError: If a referenced variable is not found
        CircularReferenceError: If a circular variable reference is detected

    Examples:
        >>> import envresolve
        >>> # Idempotent - plain strings pass through
        >>> value = envresolve.resolve_secret("just-a-string")
        >>> value
        'just-a-string'
        >>> # Non-target URIs pass through unchanged
        >>> uri = envresolve.resolve_secret("postgres://localhost/db")
        >>> uri
        'postgres://localhost/db'
        >>> # Secret URIs require provider registration and authentication
        >>> # envresolve.register_azure_kv_provider()
        >>> # secret = envresolve.resolve_secret("akv://my-vault/db-password")
    """
    return _default_resolver.resolve_secret(uri)

load_env 

load_env(
    path: str | Path = ".env",
    *,
    export: bool = True,
    override: bool = False,
) -> dict[str, str]

Load environment variables from a .env file and resolve secret URIs.

This function: 1. Loads variables from the .env file 2. Expands variable references within values 3. Resolves secret URIs (akv://) to actual secret values 4. Optionally exports to os.environ

Parameters:

Name Type Description Default
path str | Path

Path to .env file (default: ".env")

 '.env'
export bool

If True, export resolved variables to os.environ (default: True)

 True
override bool

If True, override existing os.environ variables (default: False)

 False

Returns:

Type Description
dict[str, str]

Dictionary of resolved environment variables

Raises:

Type Description
FileNotFoundError

If the .env file doesn't exist
URIParseError

If a URI format is invalid
SecretResolutionError

If secret resolution fails
VariableNotFoundError

If a referenced variable is not found
CircularReferenceError

If a circular variable reference is detected

Examples:

>>> import envresolve
>>> envresolve.register_azure_kv_provider()
>>> # Load and export to os.environ
>>> resolved = envresolve.load_env(".env", export=True)
>>> # Load without exporting
>>> resolved = envresolve.load_env(".env", export=False)
Source code in src/envresolve/api.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
def load_env(
    path: str | Path = ".env",
    *,
    export: bool = True,
    override: bool = False,
) -> dict[str, str]:
    """Load environment variables from a .env file and resolve secret URIs.

    This function:
    1. Loads variables from the .env file
    2. Expands variable references within values
    3. Resolves secret URIs (akv://) to actual secret values
    4. Optionally exports to os.environ

    Args:
        path: Path to .env file (default: ".env")
        export: If True, export resolved variables to os.environ (default: True)
        override: If True, override existing os.environ variables (default: False)

    Returns:
        Dictionary of resolved environment variables

    Raises:
        FileNotFoundError: If the .env file doesn't exist
        URIParseError: If a URI format is invalid
        SecretResolutionError: If secret resolution fails
        VariableNotFoundError: If a referenced variable is not found
        CircularReferenceError: If a circular variable reference is detected

    Examples:
        >>> import envresolve
        >>> envresolve.register_azure_kv_provider()
        >>> # Load and export to os.environ
        >>> resolved = envresolve.load_env(".env", export=True)  # doctest: +SKIP
        >>> # Load without exporting
        >>> resolved = envresolve.load_env(".env", export=False)  # doctest: +SKIP
    """
    return _default_resolver.load_env(path, export=export, override=override)