plox.tools.environment

Assorted utilities for dealing with anything related the current process’ environment.

from plox.tools import environment

Exceptions

MissingEnvironmentVariableError

Custom exception to represent a missing environment variable.

Functions

add_to_env_from_file(environment_file)

Add a set of key=value pairs from an env file to the current environment.

ensure_envars_set(to_validate[, are_paths, create_ok])

Validate that a list of variables exists in current environment.

envvar_or_bail(k)

Read and return an environment variable or raise an Exception.

modified_environ(*remove, **update)

Temporarily modify process environment within a contextmanger wrapping.

parse_environment_file_to_values(envfile[, expand_vars])

Parse local file containing key=value environment pairs into their values and return as dict.

Module Contents

exception plox.tools.environment.MissingEnvironmentVariableError

Bases: Exception

Custom exception to represent a missing environment variable.

plox.tools.environment.add_to_env_from_file(environment_file)

Add a set of key=value pairs from an env file to the current environment.

The environment file should consistent of a set of <keys>=<values> where the keys represent environment variable names, and <values> are their value.

For example, if the following envfile resided at /tmp/foo.env:

FOOBAR=/tmp/some_key
FOOBAZ=${HOME}/some_other_key

add_to_env_from_file("/tmp/foo.env") would result in the following items being added to the process’ environ:

{"FOOBAR": "/tmp/some_key", "FOOBAZ": "<expanded HOME variable>/some_other_key"}
Parameters:

environment_file (plox.tools.files.FilePath) – Path to local file on disk containing vars to parse into environment.

plox.tools.environment.ensure_envars_set(to_validate, are_paths=False, create_ok=False)

Validate that a list of variables exists in current environment.

Parameters:

  • to_validate (list[str]) – A list of envar names to check existence of.

  • are_paths (bool) – Whether or not the envars are representing local file system paths that should exist; if set to True, each envar’s value will be checked to ensure is an existing path.

  • create_ok (bool) – Whether or not the path should be created if not existent.

Raises:

  • MissingEnvironmentVariableError – If any specified items in to_validate are not in present env.

  • OSError – If error encountered when trying to make directory to path when are_paths is also True.

plox.tools.environment.envvar_or_bail(k)

Read and return an environment variable or raise an Exception.

Parameters:

k (str) – Key name for environment variable to read.

Raises:

MissingEnvironmentVariableError – If specified k not in present env.

Returns:

Value of environment variable

Return type:

str

plox.tools.environment.modified_environ(*remove, **update)

Temporarily modify process environment within a contextmanger wrapping.

Will remove and/or update process’ environment values based on based arguments. Useful for running a command/sub-process with a temporarily modified env. If "ALL" is passed as an argument to remove, then the entirety of the existing environment will be removed.

Example

>>> # removing all vars
>>> from plox.tools.environment import modified_environ
>>> from os import environ
>>> len(environ)
72
>>> with modified_environ("ALL"):
>>>     print(len(env))
0
>>> len(environ)
72
>>> # Adding a temporary var
>>> environ.get("FOOBAR", "not set")
'not set'
>>> with modified_environ(FOOBAR="set"):
>>>     print(environ.get("FOOBAR", "not set"))
set
>>> environ.get("FOOBAR", "not set")
'not set'
>>> # both
>>> with modified_environ("ALL", FOOBAR="set"):
>>>     print(len(env))
1
Parameters:

  • remove (str) – Name of environment variables to _remove_ from the environment.

  • update (str) – Dictionary pairing of key:value items to _add_ to the environment.

Returns:

Modified envrionment that will be reverted upon context manager exiting scope.

Return type:

Generator[None, None, None]

plox.tools.environment.parse_environment_file_to_values(envfile, expand_vars=True)

Parse local file containing key=value environment pairs into their values and return as dict.

The environment file should consistent of a set of <keys>=<values> where the keys represent environment variable names, and <values> are their value.

An example envfile:

FOOBAR=/tmp/some_key
FOOBAZ=${HOME}/some_other_key

parse_environment_file_to_values would return the following dict:

{"FOOBAR": "/tmp/some_key", "FOOBAZ": "<expanded HOME variable>/some_other_key"}
Parameters:

  • envfile (plox.tools.files.FilePath) – Path to local file on disk containing vars to parse into the environment.

  • expand_vars (bool) – Whether or not to expand variables in the values. Default true.

Returns:

The dictionary representing the key:value pairs of the env file.

Return type:

dict[Any, Any]