htesp.config

Configuration loading for HTESP.

This module replaces the original check_json.config(), which

• looked only in ./config.json and then blindly at ../../config.json,

• returned None when nothing was found (every caller then raised TypeError several frames later),

• re-parsed the file on each of its ~40 call sites, and

• carried the Materials Project API key in the file itself.

The replacement

• searches the current directory and its parents (up to SEARCH_DEPTH levels) plus $HTESP_CONFIG,

• deep-merges whatever it finds over the packaged default (htesp/data/config.json), so a configuration written for an older schema still has every key the current code reads,

• caches the result per resolved path, and

• takes the API key from $MP_API_KEY or ~/.config/htesp/credentials in preference to the file.

The public entry point keeps the old name and the old return type:

from htesp.config import config
cfg = config()          # plain dict, never None

Module Attributes

CONFIG_FILENAME	file name looked for in the working directory and its parents
SEARCH_DEPTH	how many parent directories are searched above the working directory.
DEFAULT_CONFIG_PATH	packaged fallback -- the canonical, fully-populated schema
API_KEY_ENV	environment variable holding the Materials Project API key
CREDENTIALS_PATH	file consulted when API_KEY_ENV is unset
API_KEY_PLACEHOLDER	placeholder shipped in every example configuration
REQUIRED_SECTIONS	keys every configuration must resolve to something usable

Functions

api_key([cfg])	Materials Project API key: environment, then credentials file, then config.
clear_cache()	Forget every parsed configuration (used by the tests).
config([start, strict])	Return the effective configuration as a plain dict.
config_path([start])	The file config() would read, or None for the packaged default.
find_config([start])	Return the first config.json at or above start.
require_api_key([cfg])	api_key(), but raise a message that says how to set it.
validate([cfg])	Return a list of human-readable problems with cfg (empty == fine).

Exceptions

ConfigError

Raised by config() in strict mode and by require_api_key().

htesp.config.CONFIG_FILENAME = 'config.json'

file name looked for in the working directory and its parents

htesp.config.SEARCH_DEPTH = 5

how many parent directories are searched above the working directory. The bash layer runs helpers from R<id>-<comp>/<stage>/ (two levels), from R<id>-<comp>/pressure/R.../relax (four levels) and one level deeper again for phonopy supercells, hence five.

htesp.config.DEFAULT_CONFIG_PATH = PosixPath('/home/runner/work/HTESP/HTESP/htesp/data/config.json')

packaged fallback – the canonical, fully-populated schema

htesp.config.API_KEY_ENV = 'MP_API_KEY'

environment variable holding the Materials Project API key

htesp.config.CREDENTIALS_PATH = PosixPath('/home/runner/.config/htesp/credentials')

file consulted when API_KEY_ENV is unset

htesp.config.API_KEY_PLACEHOLDER = 'use_your_API_KEY'

placeholder shipped in every example configuration

exception htesp.config.ConfigError

Raised by config() in strict mode and by require_api_key().

htesp.config.find_config(start: PathLike | str | None = None) → Path | None

Return the first config.json at or above start.

$HTESP_CONFIG wins over the directory search, so a whole campaign can share one file without copying it into every working directory.

htesp.config.config(start: PathLike | str | None = None, strict: bool = False) → dict

Return the effective configuration as a plain dict.

Always returns a usable mapping: when no config.json is found the packaged default is returned, so importing a module no longer depends on the working directory. strict=True raises ConfigError instead, for commands that genuinely need the user’s own settings.

htesp.config.config_path(start: PathLike | str | None = None) → Path | None

The file config() would read, or None for the packaged default.

htesp.config.clear_cache() → None

Forget every parsed configuration (used by the tests).

htesp.config.api_key(cfg: Mapping[str, Any] | None = None) → str | None

Materials Project API key: environment, then credentials file, then config.

Returns None when only the shipped placeholder is available, so callers can give a useful message rather than sending use_your_API_KEY to the MP servers.

htesp.config.require_api_key(cfg: Mapping[str, Any] | None = None) → str

api_key(), but raise a message that says how to set it.

htesp.config.REQUIRED_SECTIONS = ('job_script', 'mpi_key', 'download', 'conv_test', 'magmom', 'pseudo', 'substitute', 'pwscf_in', 'strain', 'wanniertools_input', 'kptden', 'chull_cutoff', 'kpt_opt', 'elph_mode', 'plot')

keys every configuration must resolve to something usable

htesp.config.validate(cfg: Mapping[str, Any] | None = None) → list[str]

Return a list of human-readable problems with cfg (empty == fine).