Shared support

Overview

Several modules are used by all three stages. They provide the base table class, the global logger, label generation, the column-definition data, and a library of utilities.

common – base class, logging, and CLI

metadata_tools.common holds:

  • Table, the base class for every table kind (see Architecture).

  • The global pdslogger.PdsLogger, obtained through get_logger() and configured per run by init_logger(). Library code logs through this logger; it never uses logging directly or bare print.

  • The shared argument parser get_common_args(), which the per-stage get_args functions extend. Its volume_arg / metadata_arg / output_arg parameters select which positional path arguments a stage takes, and PathAction normalizes path separators while preserving URI prefixes.

  • CLI argument helpers shared across all three stages.

task_list_support – cloud task files

metadata_tools.task_list_support creates and writes the JSON task files consumed by rms-cloud-tasks workers. The four public functions are:

  • make_task() – builds a single task dict for one volume ID.

  • task_generator() – yields one task dict per volume without touching the filesystem.

  • scan_volumes() – walks a directory tree and returns the sorted list of volume IDs it contains.

  • write_task_file() – writes the JSON task list for a volume list to a local or remote path.

label_support – PDS3 labels

create() generates a .lbl label for a table by rendering the host’s template (or a shared template from the global templates/ directory) with rms-pdstemplate. The inventory table uses no table preprocessor; the other kinds use the PDS3 table preprocessor so column definitions are validated against the data.

columns – geometry column definitions

The metadata_tools.columns package assembles and re-exports the geometry column-definition tables for the body, ring, sky, and sun tables (see Geometry column definitions). The per-body dictionaries are built at import time by substituting each body name into a placeholder (BODYX) in the generic column lists. Because this substitution runs at import, the oops body registry must already be populated (see bodies below).

bodies – the oops body registry

get_bodies() builds the mapping from body name to oops Body object, including each primary’s regular children. get_bodies_registry() returns a cached singleton (computed once on first call). This requires the host’s oops module to have been initialized first (so SPICE bodies are registered), which is why metadata_tools.bodies is excluded from the hermetic test coverage and stubbed in the test fixtures.

util and defs

metadata_tools.util is the utility library: path helpers built on FCPath (select_dir(), get_index_name(), parse_template_name(), get_volume_glob()), text-file read/write helpers that work for local and remote paths, spacecraft-clock parsing/formatting, the placeholder-substitution helpers used by the columns package (replace(), replacement_dict()), and the cyclic-range estimator used by longitude columns.

metadata_tools.defs holds the constants: the planet name list (BODY_NAMES), the ring-system radii, the global template path, and the BODYX placeholder.

Invariants

  • Paths. Every file access goes through FCPath so local and remote storage are interchangeable; do not downcast to pathlib.Path or str. The package never creates directories through FCPath.

  • Logging. There is a single global logger; per-run handlers are added by init_logger().

  • Import order. The get_bodies_registry() singleton and the metadata_tools.columns tables are computed at import and depend on an initialized oops registry.

API reference

See Core and support, task_list_support, and Geometry column definitions.