aeat.core.env_io module

Read and rewrite simple KEY=VALUE .env files in place.

The bootstrap workflow persists resource identifiers (Drive folder, Sheets ID, Docs ID) back into env/.env after authenticated API calls create them. This module provides a dependency-free reader and writer that preserves comments, blank lines, and key ordering so hand-edited annotations survive automated rewrites.

The implementation is intentionally minimal: it does not interpret quoting, variable expansion, or multi-line values. env/.env is a flat key/value file in this project and any deviation from that shape is treated as an error.

The boundary is file persistence only. Runtime configuration still flows through Settings, load_settings(), and override_settings(); this module does not inspect or mutate process environment variables.

The public surface is read_env_file(), write_env_var(), and write_env_vars(); each takes a Path target. Malformed input raises CoreValidationError, while writers use _atomic_write_text() so the .env file is replaced atomically.

read_env_file(path)[source]

Parse KEY=VALUE lines from an env file into a flat mapping.

Comments and blank lines are skipped. Trailing newlines on values are stripped. Lines that look like KEY= (empty value) yield an empty string. The returned mapping is a file snapshot for setup and bootstrap workflows; it is not the effective runtime settings model.

Parameters:

path (Path) – Filesystem path to the env file.

Return type:

dict[str, str]

Returns:

Mapping of variable name to its raw string value. Returns an empty mapping if the file does not exist.

Raises:

CoreValidationError – When a non-comment, non-blank line does not contain an = separator.

write_env_var(path, key, value)[source]

Write or update a single KEY=VALUE entry in an env file.

Existing comments and blank lines are preserved. If the key already exists, its line is rewritten in place. Otherwise the new entry is appended to the end of the file. The write goes through write_env_vars() so single-key updates share the same atomic file replacement path as batch updates.

Parameters:

  • path (Path) – Filesystem path to the env file. Created if missing.

  • key (str) – Variable name to write.

  • value (str) – String value to assign.

Return type:

None

write_env_vars(path, mapping)[source]

Write or update multiple KEY=VALUE entries in an env file.

Existing keys are rewritten in place; new keys are appended in the order given. Comments and blank lines in the existing file are preserved verbatim. Keys absent from mapping are left untouched; this helper persists setup results without acting as an env-file normalizer or deleting operator annotations.

Parameters:

  • path (Path) – Filesystem path to the env file. Created if missing along with parent directories.

  • mapping (dict[str, str]) – Mapping of variable name to value to write.

Return type:

None