Skip to content

API Reference

getenv_bool(var_name, default=None, required=True) 

getenv_bool(
    var_name: str,
    default: bool | None = None,
    required: Literal[True] = True,
) -> bool

getenv_bool(
    var_name: str,
    default: bool | None = None,
    required: Literal[False] = False,
) -> bool | None

getenv_bool(
    var_name: str,
    default: bool | None = None,
    required: bool = False,
) -> bool | None

Get the value of a bool environment variable var_name

If the environment variable is not set
  • If required is True, a RuntimeError is raised indicating that the variable is mandatory.
  • If required is False, the function returns the default value, which may be None if no default is provided.

Valid boolean strings are case-insensitive. Acceptable values are:

 | True values | False values |
 |--------------|--------------|
 | "true"       | "false"      |
 | "1"          | "0"          |
 | "yes"        | "no"         |
 | "y"          | "n"          |
 | "on"         | "off"        |
 | "enable"     | "disable"    |
 | "enabled"    | "disabled"   |
 | "t"          | "f"          |

Args: var_name (str): The name of the environment variable to retrieve. default (bool | None, optional): The value to return if the environment variable is not set and required is False. Defaults to None. required (bool, optional): Whether the environment variable is mandatory. If True and the variable is not set, a RuntimeError is raised. Defaults to True.

Returns: bool | None: The boolean value of the environment variable, or the default if the variable is missing and not required.

Raises: TypeError: If the environment variable is set but cannot be converted to a boolean. RuntimeError: If the environment variable is required but not set.

Source code in pysafe_config/__init__.py 
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
def getenv_bool(
    var_name: str, default: bool | None = None, required: bool = True
) -> bool | None:
    """
    Get the value of a bool environment variable `var_name`

    If the environment variable is not set:
        - If `required` is True, a RuntimeError is raised indicating that the variable
          is mandatory.
        - If `required` is False, the function returns the default value, which may be
          None if no default is provided.

     Valid boolean strings are case-insensitive.
     Acceptable values are:

         | True values | False values |
         |--------------|--------------|
         | "true"       | "false"      |
         | "1"          | "0"          |
         | "yes"        | "no"         |
         | "y"          | "n"          |
         | "on"         | "off"        |
         | "enable"     | "disable"    |
         | "enabled"    | "disabled"   |
         | "t"          | "f"          |

     Args:
         var_name (str): The name of the environment variable to retrieve.
         default (bool | None, optional): The value to return if the environment variable
             is not set and required is False. Defaults to None.
         required (bool, optional): Whether the environment variable is mandatory. If True
             and the variable is not set, a RuntimeError is raised. Defaults to True.

     Returns:
         bool | None: The boolean value of the environment variable, or the default if
         the variable is missing and not required.

     Raises:
         TypeError: If the environment variable is set but cannot be converted to a boolean.
         RuntimeError: If the environment variable is required but not set.
    """
    from pysafe_config._helper_bool import _str_to_bool

    return _getenv(var_name, bool, _str_to_bool, default=default, required=required)

getenv_float(var_name, default=None, required=True) 

getenv_float(
    var_name: str,
    default: float | None = None,
    required: Literal[True] = True,
) -> float

getenv_float(
    var_name: str,
    default: float | None = None,
    required: Literal[False] = False,
) -> float | None

getenv_float(
    var_name: str,
    default: float | None = None,
    required: bool = False,
) -> float | None

Get the value of a float environment variable var_name

If the environment variable is not set: - If required is True, a RuntimeError is raised indicating that the variable is mandatory. - If required is False, the function returns the default value, which may be None if no default is provided.

Valid float strings must: - Contain only digits (0-9), optionally preceded by a single + or - sign - Include exactly one decimal point to separate the whole and fractional parts - Not contain any whitespace, commas, or alphabetic characters

Examples:

 | Valid strings | Invalid strings |
 |----------------|-----------------|
 | "50.2"         | "50"            |
 | "-0.0"         | "5.5.5"         |
 | "+1000.5"      | " 12.3"         |
 | "-99.0"        | "12,3"          |
 | "0.0001"       | "ten"           |
 | "+.5"          | "5."            |
 | "-1.23"        | "" (empty)      |

Args: var_name (str): The name of the environment variable to retrieve. default (float | None, optional): The value to return if the environment variable is not set and required is False. Defaults to None. required (bool, optional): Whether the environment variable is mandatory. If True and the variable is not set, a RuntimeError is raised. Defaults to True.

Returns: float | None: The string value of the environment variable, or the default if the variable is missing and not required.

Raises: TypeError: If the environment variable is set but cannot be converted to a string. RuntimeError: If the environment variable is required but not set.

Source code in pysafe_config/__init__.py 
 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
def getenv_float(
    var_name: str, default: float | None = None, required: bool = True
) -> float | None:
    """
    Get the value of a float environment variable `var_name`

     If the environment variable is not set:
         - If `required` is True, a RuntimeError is raised indicating that the variable
           is mandatory.
         - If `required` is False, the function returns the default value, which may be
           None if no default is provided.

     Valid float strings must:
         - Contain only digits (`0-9`), optionally preceded by a single `+` or `-` sign
         - Include exactly one decimal point to separate the whole and fractional parts
         - Not contain any whitespace, commas, or alphabetic characters

     Examples:

         | Valid strings | Invalid strings |
         |----------------|-----------------|
         | "50.2"         | "50"            |
         | "-0.0"         | "5.5.5"         |
         | "+1000.5"      | " 12.3"         |
         | "-99.0"        | "12,3"          |
         | "0.0001"       | "ten"           |
         | "+.5"          | "5."            |
         | "-1.23"        | "" (empty)      |

     Args:
         var_name (str): The name of the environment variable to retrieve.
         default (float | None, optional): The value to return if the environment variable
             is not set and required is False. Defaults to None.
         required (bool, optional): Whether the environment variable is mandatory. If True
             and the variable is not set, a RuntimeError is raised. Defaults to True.

     Returns:
         float | None: The string value of the environment variable, or the default if
         the variable is missing and not required.

     Raises:
         TypeError: If the environment variable is set but cannot be converted to a string.
         RuntimeError: If the environment variable is required but not set.
    """
    from pysafe_config._helper_float import _str_to_float

    return _getenv(var_name, float, _str_to_float, default=default, required=required)

getenv_int(var_name, default=None, required=True) 

getenv_int(
    var_name: str,
    default: int | None = None,
    required: Literal[True] = True,
) -> int

getenv_int(
    var_name: str,
    default: int | None = None,
    required: Literal[False] = False,
) -> int | None

getenv_int(
    var_name: str,
    default: int | None = None,
    required: bool = False,
) -> int | None

Get the value of an int environment variable var_name

If the environment variable is not set: - If required is True, a RuntimeError is raised indicating that the variable is mandatory. - If required is False, the function returns the default value, which may be None if no default is provided.

Valid integer environment variables must: - Contain only digits (0-9), optionally preceded by a single + or - sign - Not contain any whitespace - Not include decimal points, letters, or special symbols

Examples:

 | Valid strings | Invalid strings |
 |----------------|-----------------|
 | "100"          | " 100"          |
 | "1"            | "10.5"          |
 | "-50"          | "1,000"         |
 | "+1000"        | "12a"           |
 | "0"            | "++5"           |
 | "-0"           | "5-"            |
 | "123456        | "ten"           |
 | "-123456"      | "" (empty)      |

Args: var_name (str): The name of the environment variable to retrieve. default (int | None, optional): The value to return if the environment variable is not set and required is False. Defaults to None. required (bool, optional): Whether the environment variable is mandatory. If True and the variable is not set, a RuntimeError is raised. Defaults to True.

Returns: int | None: The string value of the environment variable, or the default if the variable is missing and not required.

Raises: TypeError: If the environment variable is set but cannot be converted to a string. RuntimeError: If the environment variable is required but not set.

Source code in pysafe_config/__init__.py 
183
184
185
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
221
222
223
224
225
226
227
228
229
230
231
def getenv_int(
    var_name: str, default: int | None = None, required: bool = True
) -> int | None:
    """
    Get the value of an int environment variable `var_name`

     If the environment variable is not set:
         - If `required` is True, a RuntimeError is raised indicating that the variable
           is mandatory.
         - If `required` is False, the function returns the default value, which may be
           None if no default is provided.

     Valid integer environment variables must:
         - Contain only digits (`0-9`), optionally preceded by a single `+` or `-` sign
         - Not contain any whitespace
         - Not include decimal points, letters, or special symbols

     Examples:

         | Valid strings | Invalid strings |
         |----------------|-----------------|
         | "100"          | " 100"          |
         | "1"            | "10.5"          |
         | "-50"          | "1,000"         |
         | "+1000"        | "12a"           |
         | "0"            | "++5"           |
         | "-0"           | "5-"            |
         | "123456        | "ten"           |
         | "-123456"      | "" (empty)      |

     Args:
         var_name (str): The name of the environment variable to retrieve.
         default (int | None, optional): The value to return if the environment variable
             is not set and required is False. Defaults to None.
         required (bool, optional): Whether the environment variable is mandatory. If True
             and the variable is not set, a RuntimeError is raised. Defaults to True.

     Returns:
         int | None: The string value of the environment variable, or the default if
         the variable is missing and not required.

     Raises:
         TypeError: If the environment variable is set but cannot be converted to a string.
         RuntimeError: If the environment variable is required but not set.
    """

    from pysafe_config._helper_int import _str_to_int

    return _getenv(var_name, int, _str_to_int, default=default, required=required)

getenv_str(var_name, default=None, required=True) 

getenv_str(
    var_name: str,
    default: str | None = None,
    required: Literal[True] = True,
) -> str

getenv_str(
    var_name: str,
    default: str | None = None,
    required: Literal[False] = False,
) -> str | None

getenv_str(
    var_name: str,
    default: str | None = None,
    required: bool = False,
) -> str | None

Get the value of a str environment variable var_name

If the environment variable is not set: - If required is True, a RuntimeError is raised indicating that the variable is mandatory. - If required is False, the function returns the default value, which may be None if no default is provided.

Args: var_name (str): The name of the environment variable to retrieve. default (str | None, optional): The value to return if the environment variable is not set and required is False. Defaults to None. required (bool, optional): Whether the environment variable is mandatory. If True and the variable is not set, a RuntimeError is raised. Defaults to True.

Returns: str | None: The string value of the environment variable, or the default if the variable is missing and not required.

Raises: TypeError: If the environment variable is set but cannot be converted to a string. RuntimeError: If the environment variable is required but not set.

Source code in pysafe_config/__init__.py 
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
165
166
167
168
def getenv_str(
    var_name: str, default: str | None = None, required: bool = True
) -> str | None:
    """
    Get the value of a str environment variable `var_name`

     If the environment variable is not set:
         - If `required` is True, a RuntimeError is raised indicating that the variable
           is mandatory.
         - If required is False, the function returns the default value, which may be
           None if no default is provided.

     Args:
         var_name (str): The name of the environment variable to retrieve.
         default (str | None, optional): The value to return if the environment variable
             is not set and required is False. Defaults to None.
         required (bool, optional): Whether the environment variable is mandatory. If True
             and the variable is not set, a RuntimeError is raised. Defaults to True.

     Returns:
         str | None: The string value of the environment variable, or the default if
         the variable is missing and not required.

     Raises:
         TypeError: If the environment variable is set but cannot be converted to a string.
         RuntimeError: If the environment variable is required but not set.
    """
    from pysafe_config._helper_str import _str_to_str

    return _getenv(var_name, str, _str_to_str, default=default, required=required)