Helper Functions

envdot provides type-specific helper functions that serve as enhanced replacements for os.getenv(). These functions ensure you get properly typed values from environment variables.

Typed Getters

getenv_typed()

envdot.getenv_typed(key, default=None)

Get an environment variable with automatic type detection.

Parameters:

key (str) – The variable name
default (Any) – Default value if key doesn’t exist

Returns:

Value with automatically detected type

Return type:

bool, int, float, str, or None

Example:

from envdot import getenv_typed

# Auto-detects types
debug = getenv_typed('DEBUG')      # True (bool)
port = getenv_typed('PORT')        # 8080 (int)
timeout = getenv_typed('TIMEOUT')  # 30.5 (float)
name = getenv_typed('APP_NAME')    # 'MyApp' (str)

getenv_int()

envdot.getenv_int(key, default=None)

Get an environment variable as an integer.

Parameters:

key (str) – The variable name
default (int or None) – Default value if key doesn’t exist (default: None)

Returns:

Integer value

Return type:

int or None

Raises:

ValueError – If value cannot be converted to int

Example:

from envdot import getenv_int

port = getenv_int('PORT', default=8000)
workers = getenv_int('MAX_WORKERS', default=4)
retries = getenv_int('MAX_RETRIES', default=3)

getenv_bool()

envdot.getenv_bool(key, default=None)

Get an environment variable as a boolean.

Parameters:

key (str) – The variable name
default (bool or None) – Default value if key doesn’t exist (default: None)

Returns:

Boolean value

Return type:

bool or None

Recognized true values: true, yes, on, 1 Recognized false values: false, no, off, 0

Example:

from envdot import getenv_bool

debug = getenv_bool('DEBUG', default=False)
ssl_enabled = getenv_bool('SSL_ENABLED', default=True)
verbose = getenv_bool('VERBOSE', default=False)

getenv_float()

envdot.getenv_float(key, default=None)

Get an environment variable as a float.

Parameters:

key (str) – The variable name
default (float or None) – Default value if key doesn’t exist (default: None)

Returns:

Float value

Return type:

float or None

Raises:

ValueError – If value cannot be converted to float

Example:

from envdot import getenv_float

timeout = getenv_float('TIMEOUT', default=30.0)
rate_limit = getenv_float('RATE_LIMIT', default=1.5)
threshold = getenv_float('THRESHOLD', default=0.75)

getenv_str()

envdot.getenv_str(key, default=None)

Get an environment variable as a string (no type conversion).

Parameters:

key (str) – The variable name
default (str or None) – Default value if key doesn’t exist (default: None)

Returns:

String value

Return type:

str or None

Example:

from envdot import getenv_str

app_name = getenv_str('APP_NAME', default='MyApp')
api_key = getenv_str('API_KEY', default='')
version = getenv_str('VERSION', default='1.0.0')

Typed Setter

setenv_typed()

envdot.setenv_typed(key, value)

Set an environment variable with proper type handling.

Parameters:

key (str) – The variable name
value (Any) – The value to set (any type)

Returns:

None

Example:

from envdot import setenv_typed

setenv_typed('DEBUG', True)
setenv_typed('PORT', 8080)
setenv_typed('TIMEOUT', 30.5)
setenv_typed('APP_NAME', 'MyApp')

OS Module Patching

patch_os_module()

envdot.patch_os_module()

Patch the os module to add typed environment variable methods.

After calling this function, the os module will have the following additional methods:

os.getenv_typed()
os.getenv_int()
os.getenv_bool()
os.getenv_float()
os.getenv_str()
os.setenv_typed()

Example:

from envdot import patch_os_module
import os

# Patch the os module
patch_os_module()

# Now os has typed methods
debug = os.getenv_bool('DEBUG', default=False)
port = os.getenv_int('PORT', default=8000)
timeout = os.getenv_float('TIMEOUT', default=30.0)

# Set typed values
os.setenv_typed('NEW_PORT', 9000)
os.setenv_typed('FEATURE_ENABLED', True)

Comparison: Standard vs Typed

Here’s why typed helpers are useful:

Standard os.getenv() - always returns strings:

import os

os.environ['PORT'] = '8080'
os.environ['DEBUG'] = 'true'

port = os.getenv('PORT')   # '8080' (str)
debug = os.getenv('DEBUG') # 'true' (str)

# Manual conversion required
port = int(os.getenv('PORT', '8000'))
debug = os.getenv('DEBUG', 'false').lower() in ('true', 'yes', '1', 'on')

envdot helpers - properly typed:

from envdot import getenv_int, getenv_bool

port = getenv_int('PORT', default=8000)   # 8080 (int)
debug = getenv_bool('DEBUG', default=False) # True (bool)

# No manual conversion needed!

Complete Example

from envdot import (
    load_env,
    getenv_typed,
    getenv_int,
    getenv_bool,
    getenv_float,
    getenv_str,
    setenv_typed
)

# Load environment
load_env('.env')

# Database configuration
db_config = {
    'host': getenv_str('DB_HOST', default='localhost'),
    'port': getenv_int('DB_PORT', default=5432),
    'pool_size': getenv_int('DB_POOL_SIZE', default=5),
    'timeout': getenv_float('DB_TIMEOUT', default=30.0),
    'ssl_enabled': getenv_bool('DB_SSL', default=False),
}

# Application settings
app_config = {
    'debug': getenv_bool('DEBUG', default=False),
    'port': getenv_int('PORT', default=8000),
    'workers': getenv_int('WORKERS', default=4),
    'name': getenv_str('APP_NAME', default='MyApp'),
}

# Set new configuration
setenv_typed('NEW_FEATURE', True)
setenv_typed('MAX_CONNECTIONS', 100)

print("Database Config:", db_config)
print("Application Config:", app_config)