dmf.env.EnvManager

class dmf.env.EnvManager

Bases: object

A manager for handling environment variables across different levels, including user, project, and system.

The EnvManager class simplifies the management of environment variables by allowing you to load, set, unset, and retrieve variables from different sources such as user-level .env files, project-level .env files, or directly from the system’s environment variables.

Examples

Basic Usage: >>> env = EnvManager().setup() >>> env.setenv(‘API_KEY’, ‘12345’, environ=’project’) >>> print(env.getenv(‘API_KEY’)) ‘12345’ >>> del env[‘API_KEY’]

Chained Setup: >>> env = EnvManager().setup(project_env_path=”my_project.env”, user_env_path=”~/.custom_env”, override=True) >>> env.setenv(‘SECRET_KEY’, ‘abcdef’, environ=’user’)

Using Global Instance: >>> from dmf.env import env, getenv, setenv, unsetenv >>> setenv(‘DATABASE_URL’, ‘sqlite:///mydb.db’, environ=’project’) >>> print(getenv(‘DATABASE_URL’)) ‘sqlite:///mydb.db’ >>> unsetenv(‘DATABASE_URL’)

__init__()

Methods

__init__()
all([scope, pattern])	Retrieve all environment variables, optionally filtered by a pattern.
get(key[, default])	Retrieve an environment variable's value.
getenv(key[, default])	Retrieve an environment variable's value.
load(env_file)	Load environment variables from a specified file.
load_from_str(dotenv_string)	Load environment variables from a string.
setenv(key, value[, scope])	Set an environment variable.
setup([project_env_path, user_env_path, ...])	Set up the environment by loading variables from user and project .env files.
unsetenv(key[, scope])	Unset (delete) an environment variable.

all(scope: Literal['project', 'user'] | None = None, pattern: str | None = None) → Dict[str, str]

Retrieve all environment variables, optionally filtered by a pattern.

Parameters:

• scope (Optional[Literal['project', 'user']], optional) – The scope of environment variables to retrieve. If ‘project’, returns variables from the project .env file. If ‘user’, returns variables from the user .env file. If None, returns all variables from the current environment.

• pattern (Optional[str], optional) – A regex pattern to filter the environment variables by key name. Defaults to None, which means no filtering.

Returns:

A dictionary containing all environment variables in the specified scope, filtered by the pattern if provided.

Return type:

Dict[str, str]

Raises:

ValueError – If an invalid scope is provided.

get(key: str, default: str | None = None) → str | None

Retrieve an environment variable’s value.

Parameters:

• key (str) – The name of the environment variable.

• default (Optional[str], optional) – The default value to return if the environment variable is not found. Defaults to None.

Returns:

The value of the environment variable, or the default value if the variable is not set.

Return type:

Optional[str]

getenv(key: str, default: str | None = None) → str | None

Retrieve an environment variable’s value.

Parameters:

• key (str) – The name of the environment variable.

• default (Optional[str], optional) – The default value to return if the environment variable is not found. Defaults to None.

Returns:

The value of the environment variable, or the default value if the variable is not set.

Return type:

Optional[str]

load(env_file: str | Path) → None

Load environment variables from a specified file.

Parameters:

env_file (Union[str, Path]) – The path to the .env file to load.

load_from_str(dotenv_string: str) → None

Load environment variables from a string.

Parameters:

dotenv_string (str) – A string containing environment variable definitions.

setenv(key: str, value: str, scope: Literal['project', 'user'] | None = None)

Set an environment variable.

Parameters:

• key (str) – The name of the environment variable.

• value (str) – The value to set for the environment variable.

• scope (Optional[Literal["project", "user"]], optional) – The environment in which to set the variable. Can be “project” or “user”. Defaults to None.

setup(project_env_path: str | Path = '.env', user_env_path: str | Path = '~/.env.dmf', override: bool = False) → EnvManager

Set up the environment by loading variables from user and project .env files.

Parameters:

• project_env_path (Union[str, Path], optional) – The path to the project’s .env file. Defaults to “.env”.

• user_env_path (Union[str, Path], optional) – The path to the user’s .env.dmf file. Defaults to “~/.env.dmf”.

• override (bool, optional) – Whether to override existing environment variables with values from the .env files. Defaults to False.

Returns:

The initialized EnvManager instance.

Return type:

EnvManager

unsetenv(key: str, scope: Literal['project', 'user'] | None = None)

Unset (delete) an environment variable.

Parameters:

• key (str) – The name of the environment variable to unset.

• scope (Optional[Literal["project", "user"]], optional) – The environment from which to unset the variable. Can be “project” or “user”. Defaults to None.