Skip to content

Exceptions

This section details the custom exception hierarchy used in envresolve.

envresolve.exceptions

Custom exceptions for envresolve.

EnvResolveError

Bases: Exception

Base exception for all envresolve errors.

Source code in src/envresolve/exceptions.py 
4
5
class EnvResolveError(Exception):
    """Base exception for all envresolve errors."""

CircularReferenceError

Bases: EnvResolveError

Raised when a circular reference is detected in variable expansion.

Source code in src/envresolve/exceptions.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class CircularReferenceError(EnvResolveError):
    """Raised when a circular reference is detected in variable expansion."""

    def __init__(self, variable_name: str, chain: list[str] | None = None) -> None:
        """Initialize CircularReferenceError.

        Args:
            variable_name: The variable that caused the circular reference
            chain: Optional list showing the reference chain
        """
        self.variable_name = variable_name
        self.chain = chain or []
        chain_str = " -> ".join(self.chain) if self.chain else variable_name
        msg = f"Circular reference detected: {chain_str}"
        super().__init__(msg)

__init__ 

__init__(
    variable_name: str, chain: list[str] | None = None
) -> None

Initialize CircularReferenceError.

Parameters:

Name Type Description Default
variable_name str

The variable that caused the circular reference

 required
chain list[str] | None

Optional list showing the reference chain

 None
Source code in src/envresolve/exceptions.py 
11
12
13
14
15
16
17
18
19
20
21
22
def __init__(self, variable_name: str, chain: list[str] | None = None) -> None:
    """Initialize CircularReferenceError.

    Args:
        variable_name: The variable that caused the circular reference
        chain: Optional list showing the reference chain
    """
    self.variable_name = variable_name
    self.chain = chain or []
    chain_str = " -> ".join(self.chain) if self.chain else variable_name
    msg = f"Circular reference detected: {chain_str}"
    super().__init__(msg)

VariableNotFoundError

Bases: EnvResolveError

Raised when a referenced variable is not found in the environment.

Source code in src/envresolve/exceptions.py 
25
26
27
28
29
30
31
32
33
34
35
class VariableNotFoundError(EnvResolveError):
    """Raised when a referenced variable is not found in the environment."""

    def __init__(self, variable_name: str) -> None:
        """Initialize VariableNotFoundError.

        Args:
            variable_name: The variable that was not found
        """
        self.variable_name = variable_name
        super().__init__(f"Variable not found: {variable_name}")

__init__ 

__init__(variable_name: str) -> None

Initialize VariableNotFoundError.

Parameters:

Name Type Description Default
variable_name str

The variable that was not found

 required
Source code in src/envresolve/exceptions.py 
28
29
30
31
32
33
34
35
def __init__(self, variable_name: str) -> None:
    """Initialize VariableNotFoundError.

    Args:
        variable_name: The variable that was not found
    """
    self.variable_name = variable_name
    super().__init__(f"Variable not found: {variable_name}")

InvalidVariableNameError

Bases: EnvResolveError

Raised when a variable reference uses an invalid name.

Source code in src/envresolve/exceptions.py 
38
39
40
41
42
43
44
45
46
47
48
class InvalidVariableNameError(EnvResolveError):
    """Raised when a variable reference uses an invalid name."""

    def __init__(self, variable_name: str) -> None:
        """Initialize InvalidVariableNameError.

        Args:
            variable_name: The invalid variable name encountered
        """
        self.variable_name = variable_name
        super().__init__(f"Invalid variable name: {variable_name}")

__init__ 

__init__(variable_name: str) -> None

Initialize InvalidVariableNameError.

Parameters:

Name Type Description Default
variable_name str

The invalid variable name encountered

 required
Source code in src/envresolve/exceptions.py 
41
42
43
44
45
46
47
48
def __init__(self, variable_name: str) -> None:
    """Initialize InvalidVariableNameError.

    Args:
        variable_name: The invalid variable name encountered
    """
    self.variable_name = variable_name
    super().__init__(f"Invalid variable name: {variable_name}")

URIParseError

Bases: EnvResolveError

Raised when a secret URI cannot be parsed.

Source code in src/envresolve/exceptions.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
class URIParseError(EnvResolveError):
    """Raised when a secret URI cannot be parsed."""

    def __init__(self, message: str, uri: str | None = None) -> None:
        """Initialize URIParseError.

        Args:
            message: Error message describing the parsing failure
            uri: The URI that failed to parse (optional)
        """
        self.uri = uri
        full_message = f"{message}: {uri}" if uri else message
        super().__init__(full_message)

__init__ 

__init__(message: str, uri: str | None = None) -> None

Initialize URIParseError.

Parameters:

Name Type Description Default
message str

Error message describing the parsing failure

 required
uri str | None

The URI that failed to parse (optional)

 None
Source code in src/envresolve/exceptions.py 
54
55
56
57
58
59
60
61
62
63
def __init__(self, message: str, uri: str | None = None) -> None:
    """Initialize URIParseError.

    Args:
        message: Error message describing the parsing failure
        uri: The URI that failed to parse (optional)
    """
    self.uri = uri
    full_message = f"{message}: {uri}" if uri else message
    super().__init__(full_message)

SecretResolutionError

Bases: EnvResolveError

Raised when a secret cannot be resolved from its provider.

Source code in src/envresolve/exceptions.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class SecretResolutionError(EnvResolveError):
    """Raised when a secret cannot be resolved from its provider."""

    def __init__(
        self, message: str, uri: str, original_error: Exception | None = None
    ) -> None:
        """Initialize SecretResolutionError.

        Args:
            message: Error message describing the resolution failure
            uri: The URI that failed to resolve
            original_error: The original exception that caused this error (optional)
        """
        self.uri = uri
        self.original_error = original_error
        full_message = f"{message}: {uri}"
        if original_error:
            full_message = f"{full_message} (caused by: {original_error})"
        super().__init__(full_message)

__init__ 

__init__(
    message: str,
    uri: str,
    original_error: Exception | None = None,
) -> None

Initialize SecretResolutionError.

Parameters:

Name Type Description Default
message str

Error message describing the resolution failure

 required
uri str

The URI that failed to resolve

 required
original_error Exception | None

The original exception that caused this error (optional)

 None
Source code in src/envresolve/exceptions.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def __init__(
    self, message: str, uri: str, original_error: Exception | None = None
) -> None:
    """Initialize SecretResolutionError.

    Args:
        message: Error message describing the resolution failure
        uri: The URI that failed to resolve
        original_error: The original exception that caused this error (optional)
    """
    self.uri = uri
    self.original_error = original_error
    full_message = f"{message}: {uri}"
    if original_error:
        full_message = f"{full_message} (caused by: {original_error})"
    super().__init__(full_message)

ProviderRegistrationError

Bases: EnvResolveError

Raised when a provider registration fails.

Source code in src/envresolve/exceptions.py 
87
88
89
90
91
92
93
94
95
96
97
98
class ProviderRegistrationError(EnvResolveError):
    """Raised when a provider registration fails."""

    def __init__(self, message: str, original_error: Exception | None = None) -> None:
        """Initialize ProviderRegistrationError.

        Args:
            message: Error message describing the registration failure
            original_error: The original exception that caused this error (optional)
        """
        self.original_error = original_error
        super().__init__(message)

__init__ 

__init__(
    message: str, original_error: Exception | None = None
) -> None

Initialize ProviderRegistrationError.

Parameters:

Name Type Description Default
message str

Error message describing the registration failure

 required
original_error Exception | None

The original exception that caused this error (optional)

 None
Source code in src/envresolve/exceptions.py 
90
91
92
93
94
95
96
97
98
def __init__(self, message: str, original_error: Exception | None = None) -> None:
    """Initialize ProviderRegistrationError.

    Args:
        message: Error message describing the registration failure
        original_error: The original exception that caused this error (optional)
    """
    self.original_error = original_error
    super().__init__(message)

MutuallyExclusiveArgumentsError

Bases: EnvResolveError, TypeError

Raised when mutually exclusive arguments are specified together.

Source code in src/envresolve/exceptions.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class MutuallyExclusiveArgumentsError(EnvResolveError, TypeError):
    """Raised when mutually exclusive arguments are specified together."""

    def __init__(self, arg1: str, arg2: str) -> None:
        """Initialize MutuallyExclusiveArgumentsError.

        Args:
            arg1: First mutually exclusive argument name
            arg2: Second mutually exclusive argument name
        """
        self.arg1 = arg1
        self.arg2 = arg2
        msg = (
            f"Arguments '{arg1}' and '{arg2}' are mutually exclusive. "
            f"Specify either '{arg1}' or '{arg2}', but not both."
        )
        super().__init__(msg)

__init__ 

__init__(arg1: str, arg2: str) -> None

Initialize MutuallyExclusiveArgumentsError.

Parameters:

Name Type Description Default
arg1 str

First mutually exclusive argument name

 required
arg2 str

Second mutually exclusive argument name

 required
Source code in src/envresolve/exceptions.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def __init__(self, arg1: str, arg2: str) -> None:
    """Initialize MutuallyExclusiveArgumentsError.

    Args:
        arg1: First mutually exclusive argument name
        arg2: Second mutually exclusive argument name
    """
    self.arg1 = arg1
    self.arg2 = arg2
    msg = (
        f"Arguments '{arg1}' and '{arg2}' are mutually exclusive. "
        f"Specify either '{arg1}' or '{arg2}', but not both."
    )
    super().__init__(msg)

EnvironmentVariableResolutionError

Bases: EnvResolveError

Raised when an error occurs during environment variable resolution.

This exception wraps underlying errors (VariableNotFoundError, SecretResolutionError, etc.) and provides context about which environment variable was being processed.

Source code in src/envresolve/exceptions.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
class EnvironmentVariableResolutionError(EnvResolveError):
    """Raised when an error occurs during environment variable resolution.

    This exception wraps underlying errors (VariableNotFoundError,
    SecretResolutionError, etc.) and provides context about which
    environment variable was being processed.
    """

    def __init__(
        self, message: str, context_key: str, original_error: Exception
    ) -> None:
        """Initialize EnvironmentVariableResolutionError.

        Args:
            message: Error message describing what went wrong
            context_key: The environment variable name being processed
            original_error: The underlying exception that caused this error
        """
        self.context_key = context_key
        self.original_error = original_error
        super().__init__(message)

__init__ 

__init__(
    message: str,
    context_key: str,
    original_error: Exception,
) -> None

Initialize EnvironmentVariableResolutionError.

Parameters:

Name Type Description Default
message str

Error message describing what went wrong

 required
context_key str

The environment variable name being processed

 required
original_error Exception

The underlying exception that caused this error

 required
Source code in src/envresolve/exceptions.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
def __init__(
    self, message: str, context_key: str, original_error: Exception
) -> None:
    """Initialize EnvironmentVariableResolutionError.

    Args:
        message: Error message describing what went wrong
        context_key: The environment variable name being processed
        original_error: The underlying exception that caused this error
    """
    self.context_key = context_key
    self.original_error = original_error
    super().__init__(message)