DotEnv Class

The DotEnv class is the main interface for managing environment variables.

Class Reference

class envdot.DotEnv(filepath=None, auto_load=True)

Main class for environment variable management.

Parameters:

  • filepath (str or Path or None) – Path to configuration file (optional)

  • auto_load (bool) – Automatically load file on initialization (default: True)

Example:

from envdot import DotEnv

# Auto-load from .env
env = DotEnv('.env')

# Create without loading
env = DotEnv('.env', auto_load=False)

Methods

load()

DotEnv.load(filepath=None, override=True, apply_to_os=True)

Load environment variables from a file.

Parameters:

  • filepath (str or Path or None) – Path to file (uses instance filepath if not specified)

  • override (bool) – Whether to override existing values (default: True)

  • apply_to_os (bool) – Whether to apply values to os.environ (default: True)

Returns:

Self for method chaining

Return type:

DotEnv

Raises:

Example:

env = DotEnv('.env', auto_load=False)

# Basic load
env.load()

# Load from different file
env.load('config.json')

# Load without overriding existing values
env.load(override=False)

# Load without affecting os.environ
env.load(apply_to_os=False)

get()

DotEnv.get(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 (int, float, bool, str)

Returns:

The value with detected or cast type

Return type:

Any

Raises:

TypeConversionError – If cast_type is specified and conversion fails

Example:

env = DotEnv('.env')

# Get with auto type detection
debug = env.get('DEBUG')  # Returns bool
port = env.get('PORT')    # Returns int

# Get with default
timeout = env.get('TIMEOUT', default=30)

# Get with explicit type casting
version = env.get('PORT', cast_type=str)

set()

DotEnv.set(key, value, apply_to_os=True)

Set an environment variable.

Parameters:

  • key (str) – The variable name

  • value (Any) – The value to set

  • apply_to_os (bool) – Whether to also set in os.environ (default: True)

Returns:

Self for method chaining

Return type:

DotEnv

Example:

env = DotEnv('.env')

# Set various types
env.set('DEBUG', True)
env.set('PORT', 8080)
env.set('TIMEOUT', 30.5)
env.set('APP_NAME', 'MyApp')

# Set without affecting os.environ
env.set('INTERNAL', 'value', apply_to_os=False)

save()

DotEnv.save(filepath=None, format=None)

Save environment variables to a file.

Parameters:

  • filepath (str or Path or None) – Path to save file (uses instance filepath if not specified)

  • format (str or None) – File format (‘env’, ‘json’, ‘yaml’, ‘ini’) - auto-detected from extension if not specified

Returns:

Self for method chaining

Return type:

DotEnv

Example:

env = DotEnv('.env')
env.set('NEW_KEY', 'value')

# Save to original file
env.save()

# Save to new file
env.save('backup.env')

# Convert to different format
env.save('config.json')

delete()

DotEnv.delete(key, remove_from_os=True)

Delete an environment variable.

Parameters:

  • key (str) – The variable name to delete

  • remove_from_os (bool) – Whether to also remove from os.environ (default: True)

Returns:

Self for method chaining

Return type:

DotEnv

Example:

env = DotEnv('.env')

# Delete from envdot and os.environ
env.delete('OLD_KEY')

# Delete from envdot only
env.delete('TEMP_KEY', remove_from_os=False)

all()

DotEnv.all()

Get all environment variables as a dictionary.

Returns:

Dictionary of all variables

Return type:

dict

Example:

env = DotEnv('.env')
all_vars = env.all()

for key, value in all_vars.items():
    print(f"{key} = {value} ({type(value).__name__})")

keys()

DotEnv.keys()

Get all variable names.

Returns:

List of variable names

Return type:

list

Example:

env = DotEnv('.env')
for key in env.keys():
    print(key)

clear()

DotEnv.clear(clear_os=False)

Clear all stored variables.

Parameters:

clear_os (bool) – Whether to also clear from os.environ (default: False)

Returns:

Self for method chaining

Return type:

DotEnv

Example:

env = DotEnv('.env')

# Clear internal storage only
env.clear()

# Clear both internal storage and os.environ
env.clear(clear_os=True)

show()

DotEnv.show()

Display all environment variables.

Returns:

Dictionary of all variables (also prints to console)

Return type:

dict

Example:

env = DotEnv('.env')
env.show()

Magic Methods

__getitem__

DotEnv.__getitem__(key)

Dictionary-style access for getting values.

Example:

env = DotEnv('.env')
value = env['DATABASE_URL']

__setitem__

DotEnv.__setitem__(key, value)

Dictionary-style access for setting values.

Example:

env = DotEnv('.env')
env['NEW_KEY'] = 'value'

__contains__

DotEnv.__contains__(key)

Check if a key exists using in operator.

Example:

env = DotEnv('.env')
if 'API_KEY' in env:
    print("API key is configured")

__getattr__

DotEnv.__getattr__(key)

Attribute-style access for getting values.

Example:

config = DotEnv('.env')
debug = config.DEBUG
port = config.PORT

__setattr__

DotEnv.__setattr__(key, value)

Attribute-style access for setting values.

Example:

config = DotEnv('.env')
config.DEBUG = True
config.PORT = 9000

__repr__

DotEnv.__repr__()

String representation of the DotEnv instance.

Example:

env = DotEnv('.env')
print(env)  # DotEnv(filepath=.env, vars=18)