geoprior.cli.config

Shared CLI configuration helpers.

This module centralises the parser options and runtime helpers that repeat across GeoPrior CLI commands. The goal is to keep command modules small, consistent, and easy to maintain.

Scope

This module is intentionally limited to:

• repeated parser arguments such as --config and --set

• light argument aliases and normalisation

• config installation and runtime override persistence

• small path utilities used by many commands

It does not own command-specific business logic. Each command keeps its own artifact resolution and domain-specific validation.

Examples

Build a parser with shared arguments:

import argparse
from geoprior.cli._config import (
    add_city_arg,
    add_config_args,
    add_outdir_arg,
    add_results_dir_arg,
)

p = argparse.ArgumentParser()
add_config_args(p)
add_city_arg(p)
add_results_dir_arg(p)
add_outdir_arg(p)

Apply config installation and runtime overrides:

cfg = bootstrap_runtime_config(
    args,
    field_map={
        "city": "CITY_NAME",
        "model": "MODEL_NAME",
        "results_dir": "RESULTS_DIR",
    },
)

The returned cfg is the effective config dictionary after optional config installation and any --set KEY=VALUE overrides.

Functions

add_city_arg(parser, *[, dest, default, ...])	Add one or repeated --city arguments.
add_config_args(parser, *[, include_root, ...])	Add shared config installation and override arguments.
add_manifest_arg(parser, *[, dest, option, ...])	Add a manifest path argument.
add_model_arg(parser, *[, dest, default, ...])	Add --model argument.
add_outdir_arg(parser, *[, dest, default, ...])	Add output directory argument.
add_output_format_arg(parser, *[, choices, ...])	Add a reusable output format argument.
add_output_stem_arg(parser, *[, default])	Add an output stem argument for multi-file commands.
add_results_dir_arg(parser, *[, dest, default])	Add results directory argument with a root alias.
add_split_arg(parser, *[, default, choices])	Add a reusable dataset split argument.
add_stage1_dir_arg(parser)	Add --stage1-dir argument.
add_stage2_manifest_arg(parser)	Add --stage2-manifest argument.
add_validation_csv_arg(parser, *[, required])	Add external validation CSV argument.
args_to_config_overrides(args, *[, field_map])	Map parsed argument fields to config keys.
bootstrap_runtime_config(args, *[, ...])	Install config, apply overrides, and return effective cfg.
ensure_outdir(outdir)	Create and return an output directory path.
find_latest_dir(root, *[, pattern, must_contain])	Return the newest matching directory under root.
install_user_config(config_path, *[, ...])	Install a user config.py into the active config root.
parse_override_value(raw)	Parse a scalar or container value from --set.
parse_set_items(items)	Parse repeated --set KEY=VALUE items.
persist_runtime_overrides([overrides, ...])	Persist effective config to config.json.

geoprior.cli.config.parse_override_value(raw)

Parse a scalar or container value from --set.

Parameters:

raw (str) – Raw string value from the CLI.

Returns:

Parsed Python object when possible, otherwise the stripped string.

Return type:

Any

Notes

The parsing order is conservative:

1. case-insensitive booleans and none

2. integer / float literals

3. ast.literal_eval for lists, tuples, dicts, and quoted text

4. fallback to the stripped input string

geoprior.cli.config.parse_set_items(items)

Parse repeated --set KEY=VALUE items.

Parameters:

items (list[str] | tuple[str, ...] | None)

Return type:

dict[str, Any]

geoprior.cli.config.install_user_config(config_path, *, config_root='nat.com')

Install a user config.py into the active config root.

Parameters:

• config_path (str)

• config_root (str)

Return type:

str

geoprior.cli.config.persist_runtime_overrides(overrides=None, *, config_root='nat.com', refresh_fn=None)

Persist effective config to config.json.

Parameters:

• overrides (dict or None) – Optional config overrides to merge into the active config.

• config_root (str, default "nat.com") – Config root directory.

• refresh_fn (callable or None) – Optional callback used to refresh derived fields after the overrides are applied.

Return type:

dict[str, Any]

geoprior.cli.config.args_to_config_overrides(args, *, field_map=None)

Map parsed argument fields to config keys.

Parameters:

• args (argparse.Namespace) – Parsed CLI namespace.

• field_map (dict[str, str] or None) – Mapping from argument field name to config key.

Returns:

Override dictionary combining --set items and selected explicit CLI fields.

Return type:

dict

geoprior.cli.config.bootstrap_runtime_config(args, *, field_map=None, refresh_fn=None)

Install config, apply overrides, and return effective cfg.

Parameters:

• args (Namespace)

• field_map (dict[str, str] | None)

• refresh_fn (Callable[[dict[str, Any]], dict[str, Any]] | None)

Return type:

dict[str, Any]

geoprior.cli.config.ensure_outdir(outdir)

Create and return an output directory path.

Parameters:

outdir (str | Path)

Return type:

Path

geoprior.cli.config.find_latest_dir(root, *, pattern='*', must_contain=None)

Return the newest matching directory under root.

Parameters:

• root (str | Path)

• pattern (str)

• must_contain (str | None)

Return type:

Path | None

geoprior.cli.config.add_config_args(parser, *, include_root=True, include_set=True)

Add shared config installation and override arguments.

Parameters:

• parser (ArgumentParser)

• include_root (bool)

• include_set (bool)

Return type:

ArgumentParser

geoprior.cli.config.add_city_arg(parser, *, dest='city', default=None, required=False, action=None, help=None)

Add one or repeated --city arguments.

Parameters:

• parser (ArgumentParser)

• dest (str)

• default (str | None)

• required (bool)

• action (str | None)

• help (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_model_arg(parser, *, dest='model', default=None, required=False, help=None)

Add --model argument.

Parameters:

• parser (ArgumentParser)

• dest (str)

• default (str | None)

• required (bool)

• help (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_results_dir_arg(parser, *, dest='results_dir', default=None)

Add results directory argument with a root alias.

Parameters:

• parser (ArgumentParser)

• dest (str)

• default (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_manifest_arg(parser, *, dest='manifest', option='--manifest', help_text=None)

Add a manifest path argument.

Parameters:

• parser (ArgumentParser)

• dest (str)

• option (str)

• help_text (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_stage1_dir_arg(parser)

Add --stage1-dir argument.

Parameters:

parser (ArgumentParser)

Return type:

ArgumentParser

geoprior.cli.config.add_outdir_arg(parser, *, dest='outdir', default=None, required=False, help=None)

Add output directory argument.

Parameters:

• parser (ArgumentParser)

• dest (str)

• default (str | None)

• required (bool)

• help (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_output_format_arg(parser, *, choices=('csv', 'json', 'npz', 'parquet'), default=None)

Add a reusable output format argument.

Parameters:

• parser (ArgumentParser)

• choices (tuple[str, ...])

• default (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_output_stem_arg(parser, *, default=None)

Add an output stem argument for multi-file commands.

Parameters:

• parser (ArgumentParser)

• default (str | None)

Return type:

ArgumentParser

geoprior.cli.config.add_stage2_manifest_arg(parser)

Add --stage2-manifest argument.

Parameters:

parser (ArgumentParser)

Return type:

ArgumentParser

geoprior.cli.config.add_split_arg(parser, *, default=None, choices=None)

Add a reusable dataset split argument.

Parameters:

• parser (ArgumentParser)

• default (str | None)

• choices (tuple[str, ...] | None)

Return type:

ArgumentParser

geoprior.cli.config.add_validation_csv_arg(parser, *, required=False)

Add external validation CSV argument.

Parameters:

• parser (ArgumentParser)

• required (bool)

Return type:

ArgumentParser