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.

  • The cloud-task plumbing (add_task(), write_task_file(), task_source()) shared by the *_cloud.py workers.

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, and BODIES is computed once on import. 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. BODIES and the metadata_tools.columns tables are computed at import and depend on an initialized oops registry.

API reference

See Core and support and Geometry column definitions.