spindoctor.config

YAML-backed configuration for SpinDoctor.

Loads and merges settings from bundled defaults and optional user YAML files using ruamel.yaml.YAML (safe typ), then exposes sections as spindoctor.support.attrdict.AttrDict for attribute-style access. The Config class is the main public entry; helpers such as _as_str_list() validate list-shaped YAML fragments used when building config structures.

class Config[source]

Bases: object

Manages configuration settings for the navigation system.

This class handles loading, updating, and accessing configuration settings from YAML files. It provides access to various configuration sections through properties and methods.

property backplanes: Any: Returns backplanes configuration, including bodies, rings, and target LIDs.

property bodies: Any: Returns the celestial bodies configuration settings.

property body_shape: Any

Returns the per-body shape catalogue (config_220_body_shape.yaml).

Each entry is keyed by SPICE body name (e.g. MIMAS) and exposes radii_km, ellipsoid_rms_residual_km, crater_scale_km, albedo_mean, albedo_variation, and shape_class_hint. Missing-body lookups return None from AttrDict.get; downstream code applies the conservative fallback (10% radius default, reliability cap 0.3).

property bootstrap: Any: Returns the bootstrap configuration settings.

category(category: str) → AttrDict[source]

Returns the configuration settings for the specified category.

The result is cached per category and rebuilt on config reload (see _update_attrdicts), matching the caching semantics of the named section properties. Config is treated read-only; mutating the returned AttrDict is not supported.

ensure_loaded() → None[source]

Load bundled default YAML if not already loaded.

Safe to call repeatedly; delegates to read_config() with no path (same early-return behavior when data is already present).

property environment: Any: Returns the environment configuration settings.

fuzzy_satellites(planet: str) → list[str][source]

Returns the list of fuzzy satellites for the specified planet.

Parameters:: planet – The name of the planet to get fuzzy satellites for.
Returns:: A list of fuzzy satellite names for the specified planet.

property general: Any: Returns the general configuration settings.

property is_loaded: bool: Whether merged YAML is present (after read_config / update_config).

property offset: Any: Returns the offset configuration settings.

property orchestrator: Any: Returns the orchestrator (ensemble + reliability gate) settings.

property override_paths: tuple[str, ...]

The user/CLI override config files applied, in application order.

Bundled default files (the config_files glob loaded by read_config() with no path) are not overrides and never appear here; only files loaded via update_config() with read_default=True (user nav_default_config.yaml or --config-file paths) or an explicit read_config() path are recorded.

property pds4: Any: Returns PDS4 bundle generation configuration.

property planets: list[str]: Returns the list of configured planet names.

read_config(config_path: str | Path | None = None, reread: bool = False) → None[source]

Reads configuration from the specified YAML file.

Parameters:

config_path – Path to the configuration file. If None, uses the default config files.
reread – Whether to reread the configuration file if it has already been read.

Raises:

ValueError – If any registered NavTechnique’s confidence spec references an attribute the technique does not declare. Validation runs once per read_config invocation.

resolved_config_hash() → str[source]

Return a stable sha256 hex digest of the fully-resolved config.

The merged config dict (bundled defaults plus every applied override) is serialized deterministically – mapping keys are stringified and sorted, list order is preserved – and hashed, so two configs with identical resolved content produce identical digests regardless of load order or comment/whitespace changes in the source YAML files.

Returns:: 64-character sha256 hex digest of the resolved config content.

ring_satellites(planet: str) → list[str][source]

Returns the list of ring satellites for the specified planet.

Parameters:: planet – The name of the planet to get ring satellites for.
Returns:: A list of ring satellite names for the specified planet.

property rings: Any: Returns the planetary rings configuration settings.

satellites(planet: str) → list[str][source]

Returns the list of satellites for the specified planet.

Parameters:: planet – The name of the planet to get satellites for.
Returns:: A list of satellite names for the specified planet.

property stars: Any: Returns the stars configuration settings.

property titan: Any: Returns the Titan-specific configuration settings.

update_config(config_path: str | Path, read_default: bool = True) → None[source]

Updates the current configuration with values from the specified YAML file.

When read_default is true the merged YAML is re-validated against every registered NavTechnique so per-technique overrides (confidence_spec and tuning) take effect. The internal bootstrap path inside read_config() calls with read_default=False and validates once after the loop, since early default files are loaded before config_510_techniques.yaml has populated the techniques block.

Parameters:

config_path – Path to the configuration file containing update values.
read_default – Whether to read the default configuration file if no config has been previously read.

get_backplane_results_root(arguments: Namespace, config: Config) → str[source]

Get the backplane results root from the arguments, configuration, or environment.

First look in arguments.backplane_results_root, then in config.environment.backplane_results_root, then in the environment variable NAV_BACKPLANE_RESULTS_ROOT.

Parameters:

arguments – The parsed arguments. config: The configuration possibly containing the
section. (environment)

Returns:

The backplane results root.

Raises:

ValueError – If the backplane results root cannot be determined.

get_nav_results_root(arguments: Namespace, config: Config) → str[source]

Get the navigation root from the arguments, configuration, or environment.

First look in arguments.nav_results_root, then in config.environment.nav_results_root, then in the environment variable NAV_RESULTS_ROOT.

Parameters:

arguments – The parsed arguments. config: The configuration possibly containing the
section. (environment)

Returns:

The navigation results root.

Raises:

ValueError – If the navigation results root cannot be determined.

get_pds4_bundle_results_root(arguments: Namespace, config: Config) → str[source]

Get the PDS4 bundle root from the arguments, configuration, or environment.

First look in arguments.bundle_results_root, then in config.environment.bundle_results_root, then in the environment variable NAV_BUNDLE_RESULTS_ROOT.

Parameters:

arguments – The parsed arguments. config: The configuration possibly containing the
section. (environment)

Returns:

The PDS4 bundle root.

Raises:

ValueError – If the PDS4 bundle root cannot be determined.

load_default_and_user_config(arguments: Namespace, config: Config) → None[source]

Load the default and user configuration (if any).

Parameters:

arguments – The parsed arguments containing the config_file argument.
config – The configuration to update.

Logger instances and setup for the SpinDoctor pipeline.

Provides two PdsLogger instances:

MAIN_LOGGER ("sd_offset") – top-level program events, written to stdout and to a timestamped logfile under NAV_RESULTS_ROOT/logs/sd_offset/.
IMAGE_LOGGER ("nav_image") – per-image processing events; both its stdout handler and its per-image logfile handler are attached as local handlers inside each logger.open() context so they are active only while that image is being processed.

Call setup_logging() from main() after the nav-results root and CLI arguments have been resolved. It is safe to call more than once: existing MAIN_LOGGER handlers are removed before new ones are attached.

image_log_handlers(image_log_path: FCPath, arguments: Namespace | None, config: Config) → list[Handler][source]

Create local handlers for a single image: a stdout handler and a file handler.

Both levels are resolved from arguments, then config.general, then "INFO". The returned handlers should be passed to IMAGE_LOGGER.open() so they are active only while that image is being processed and are automatically removed when that context exits.

Parameters:

image_log_path – Destination path for this image’s log file.
arguments – Parsed CLI arguments, or None to fall back entirely to config.
config – Navigation configuration.

Returns:

A list containing a stdout stream handler and a file handler for the image log.

Raises:

TypeError – If a configured log level is not a string or None.
ValueError – If a configured log level string is empty or not a standard name.

setup_logging(arguments: Namespace, config: Config, nav_results_root_str: str) → None[source]

Configure MAIN_LOGGER with stdout and a timestamped file handler.

Reads each log level from arguments first, then from config.general, then falls back to "INFO". The main logfile is written as a timestamped file under {nav_results_root}/logs/sd_offset/.

IMAGE_LOGGER handlers are not configured here; both its console and per-image file handlers are attached as local handlers inside each IMAGE_LOGGER.open() context via image_log_handlers(). However, the image log levels from --log-level-image-console and --log-level-image-file are validated here so that invalid values are caught at startup (before the batch loop) alongside the main-level validation.

Parameters:

arguments – Parsed CLI arguments; may carry log_level_main_console, log_level_main_file, log_level_image_console, and log_level_image_file attributes.
config – Navigation configuration providing general.* fallback values.
nav_results_root_str – Local filesystem path to the navigation results root.

Raises:

TypeError – If a configured log level is not a string or None.
ValueError – If a configured log level string is empty or not a standard name.