Convenience Functions

envdot provides module-level convenience functions for quick and easy access to environment variables without needing to instantiate the DotEnv class.

load_env()

envdot.load_env(filepath=None, **kwargs)

Load environment variables from a file.

Parameters:

  • filepath (str or Path or None) – Path to configuration file (default: ‘.env’)

  • kwargs – Additional arguments passed to DotEnv.load()

Returns:

DotEnv instance for method chaining or attribute access

Return type:

DotEnv

Example:

from envdot import load_env

# Load from default .env
config = load_env()

# Load from specific file
config = load_env('config/production.env')

# Access values via attributes
print(config.DEBUG)
print(config.PORT)

get_env()

envdot.get_env(key, default=None, cast_type=None)

Get an environment variable with automatic type detection.

Parameters:

  • key (str) – The variable name

  • default (Any) – Default value if key doesn’t exist

  • cast_type (type or None) – Force conversion to specific type

Returns:

The value with detected or cast type

Return type:

Any

Example:

from envdot import load_env, get_env

load_env()

# Get with auto type detection
debug = get_env('DEBUG')
port = get_env('PORT')

# Get with default value
timeout = get_env('TIMEOUT', default=30)

# Get with explicit type
version = get_env('VERSION', cast_type=str)

set_env()

envdot.set_env(key, value, **kwargs)

Set an environment variable.

Parameters:

  • key (str) – The variable name

  • value (Any) – The value to set

  • kwargs – Additional arguments passed to DotEnv.set()

Returns:

None

Example:

from envdot import set_env

set_env('NEW_FEATURE', True)
set_env('MAX_WORKERS', 8)
set_env('API_URL', 'https://api.example.com')

save_env()

envdot.save_env(filepath=None, **kwargs)

Save environment variables to a file.

Parameters:

  • filepath (str or Path or None) – Path to save file

  • kwargs – Additional arguments passed to DotEnv.save()

Returns:

None

Example:

from envdot import load_env, set_env, save_env

load_env()
set_env('NEW_KEY', 'value')

# Save to original file
save_env()

# Save to different file
save_env('backup.env')

# Save as different format
save_env('config.json')

show()

envdot.show()

Display all loaded environment variables.

Returns:

Dictionary of all variables

Return type:

dict

Example:

from envdot import load_env, show

load_env()
show()

# Output:
# {'DEBUG': True,
#  'PORT': 8080,
#  'DATABASE_URL': 'postgresql://localhost/mydb',
#  ...}

Combined Example

Here’s a complete example using all convenience functions:

from envdot import load_env, get_env, set_env, save_env, show

# Load environment
config = load_env('.env')

# Display all variables
print("Current configuration:")
show()

# Get specific values
debug = get_env('DEBUG', default=False)
port = get_env('PORT', default=8000)
db_url = get_env('DATABASE_URL')

print(f"\nApplication settings:")
print(f"  Debug mode: {debug}")
print(f"  Port: {port}")
print(f"  Database: {db_url}")

# Modify configuration
set_env('DEBUG', False)
set_env('PORT', 9000)
set_env('NEW_FEATURE', True)

# Save changes
save_env()

print("\nConfiguration updated and saved!")

Comparison: Functions vs Class

Both approaches are equivalent. Choose based on your preference:

Using convenience functions:

from envdot import load_env, get_env, set_env, save_env

load_env('.env')
debug = get_env('DEBUG')
set_env('PORT', 9000)
save_env()

Using DotEnv class:

from envdot import DotEnv

env = DotEnv('.env')
debug = env.get('DEBUG')
env.set('PORT', 9000)
env.save()

The convenience functions use a shared global instance internally, making them ideal for simple applications. For more complex scenarios with multiple configuration files, use the DotEnv class directly.