Envfile

envfile

Defines functions to read, edit, and write a .env configuration file for an end-user

The .env file is stored in the application's data directory in the user's machine and is used to start the Mirumoji Docker Compose application with the configuration that was selected by the user via the launcher. It is also used to perist that information for future runs

delete_value(path, key)

Removes a single key from the .env file, preserving the others

Parameters:

Name	Type	Description	Default
path	Path	The .env file to update	required
key	str	The variable name to remove	required

Returns:

Type	Description
bool	True when the key was present and removed, False otherwise

import_file(source, target)

Merges an external .env file into the managed config file

Reads the managed target, overrides its values with the values present in source (keys absent from source are kept), and writes the merged result back to target

Parameters:

Name	Type	Description	Default
source	Path	The external .env file to import	required
target	Path	The managed config file to overwrite	required

Returns:

Type	Description
dict[str, str]	The merged values now persisted in target

Raises:

Type	Description
EnvConfigError	If source does not exist or cannot be read

missing_required(specs, values)

Returns the required environment variables that still have no value set

Checks the EnvVar.required attribute to check if the environment variable is required and appends it to a list if it doesn't contain a value in values

Parameters:

Name	Type	Description	Default
specs	Iterable[EnvVar]	The environment variables to check	required
values	Mapping[str, str]	The currently resolved values	required

Returns:

Type	Description
list[EnvVar]	The required environment variables with no non-empty values

overlay_environ(values, names)

Merges the environment variables stored in values with the ones set in the current proccess' context (accessed via os.environ) if they're listed in names

For each named variable not already set in values, adds a non-empty value from os.environ if present. The values in values take precedence when a named variable is present both in values and os.environ. Empty string values are considered as not set

Example

values = {"VAR_0": "0", "VAR_1": "V1A", "VAR_2": "V2"}
names = ["VAR_1", "VAR_2", "VAR_3"]

# os.environ = {"VAR_1": "V1B", "VAR_3": "V3"}

merged = overlay_environ(values, names)
print(merged)

# {"VAR_0": "0", "VAR_1": "V1A", "VAR_2": "V2", "VAR_3": "V3"}

Parameters:

Name	Type	Description	Default
values	Mapping[str, str]	The values read from the .env file	required
names	Iterable[str]	The variable names to consider	required

Returns:

Type	Description
dict[str, str]	A new dict combining the file values and any environment fallbacks

read(path)

Reads a .env file into a dict, ignoring blank/unset entries

Parameters:

Name	Type	Description	Default
path	Path	The .env file path	required

Returns:

Type	Description
dict[str, str]	The parsed key/value pairs, or an empty dict when the file is absent

read_deployment(env)

Parses the persisted deployment choice from the resolved values of a managed config file

Missing or unrecognised values return None so that callers can fall back to a flag or a built-in default

Parameters:

Name	Type	Description	Default
env	Mapping[str, str]	The resolved environment values	required

Returns:

Type	Description
tuple[Backend | None, ImageSource | None]	The persisted (backend, source), each None when absent/invalid

set_value(path, key, value)

Upserts a single key into the .env file, preserving the others

Parameters:

Name	Type	Description	Default
path	Path	The .env file to update	required
key	str	The variable name to set	required
value	str	The value to write	required

write(path, values)

Writes resolved values to a .env file, skipping blanks

Parameters:

Name	Type	Description	Default
path	Path	The .env file path to write to	required
values	Mapping[str, str]	The values to persist	required