geoprior.cli._dispatch#

Low-level dispatch helpers for GeoPrior command-line entry points.

This module provides the internal building blocks used by the GeoPrior CLI frontends to resolve commands, import their implementation modules, and execute the appropriate entry callable with a uniform interface.

It is intentionally small and generic. The higher-level command registry, family routing, and user-facing help pages live elsewhere, while this module focuses on the reusable mechanics required by all CLI entry points.

Overview#

The dispatcher infrastructure revolves around a small command description object, CommandSpec, and a set of helper functions that perform four main tasks:

  1. Import a command module from a registry entry.

  2. Load the entry callable exposed by that module.

  3. Execute the callable or module with the correct delegated argv and program name.

  4. Build compact command/alias listings for help output.

Design goals#

This module is designed to keep CLI execution:

  • registry-driven so commands can be described declaratively rather than hard-coded,

  • lightweight so frontends such as geoprior, geoprior-run, geoprior-build, and geoprior-plot can share the same dispatch machinery,

  • backward-compatible so legacy command names and aliases can still resolve cleanly,

  • implementation-agnostic so a command may expose either a callable entrypoint or a module-style __main__ execution path.

Execution model#

A command is described by CommandSpec, which records the target package, module, callable name, public command name, family, and accepted aliases.

Given such a specification, the helpers in this module support two execution styles:

call_entry

Load a Python callable and invoke it using the most compatible calling convention discovered from its signature.

run_module

Execute a module as __main__ after temporarily patching sys.argv, which is useful for module-oriented CLI code.

The module also provides small helpers such as alias_map(), public_items(), and print_help_table() to support consistent help rendering across command families.

Notes

This module is primarily internal and is not intended to contain domain-specific workflow logic. It should remain focused on generic dispatch behavior only.

See also

geoprior.cli.__main__

Family-aware public CLI frontends built on top of this module.

geoprior.scripts.registry

Registry definitions consumed by the dispatch layer.

Functions

alias_map(registry, *[, family])

Build alias -> public-name mapping.

call_entry(fn, *, argv, display_cmd)

Call a command entrypoint.

load_callable(spec)

Load the entry callable from a command module.

load_module(spec)

Import a module for a command spec.

print_help_table(title, items, *[, width])

Print a compact help table.

public_items(registry, *[, family])

Return public registry items filtered by family.

run_module(spec, *, display_cmd, argv)

Execute a module as __main__ with delegated argv.

Classes

CommandSpec(package, mod, fn, desc[, mode, ...])

Immutable command description used by the CLI dispatch layer.
class geoprior.cli._dispatch.CommandSpec(package, mod, fn, desc, mode='argv', family=None, public_name=None, aliases=(), legacy_names=())[source]#

Bases: object

Immutable command description used by the CLI dispatch layer.

A CommandSpec stores the minimal metadata needed to resolve and execute a command from the registry-driven GeoPrior CLI system.

Each instance identifies

  • the Python package containing the command,

  • the module to import,

  • the callable name to execute,

  • a short human-readable description,

  • the execution mode,

  • the command family and public-facing names.

Variables:

  • package (str) – Package path used for relative imports. If empty, mod is imported as an absolute module path.

  • mod (str) – Module name containing the command implementation.

  • fn (str) – Name of the callable entrypoint expected inside mod when the execution mode is callable-based.

  • desc (str) – Short help text shown in command listings.

  • mode (str, default "argv") –

    Execution strategy used by the dispatcher.

    Supported values are typically:

    • "argv" for callable entrypoints that accept delegated argument lists,

    • "sysargv" for callables relying on patched sys.argv,

    • "module" for modules executed through runpy.

  • family (str or None, default None) – Optional command family such as "run", "build", or "plot".

  • public_name (str or None, default None) – Canonical public command name exposed to users.

  • aliases (tuple of str, default ()) – Alternative spellings that resolve to public_name.

  • legacy_names (tuple of str, default ()) – Backward-compatible historical command names.

Parameters:
package: str#
mod: str#
fn: str#
desc: str#
mode: str = 'argv'#
family: str | None = None#
public_name: str | None = None#
aliases: tuple[str, ...] = ()#
legacy_names: tuple[str, ...] = ()#
__init__(package, mod, fn, desc, mode='argv', family=None, public_name=None, aliases=(), legacy_names=())#
Parameters:
Return type:

None

geoprior.cli._dispatch.load_module(spec)[source]#

Import a module for a command spec.

Parameters:

spec (CommandSpec)

geoprior.cli._dispatch.load_callable(spec)[source]#

Load the entry callable from a command module.

Parameters:

spec (CommandSpec)

Return type:

Callable[[…], None]

geoprior.cli._dispatch.run_module(spec, *, display_cmd, argv)[source]#

Execute a module as __main__ with delegated argv.

Parameters:
Return type:

None

geoprior.cli._dispatch.call_entry(fn, *, argv, display_cmd)[source]#

Call a command entrypoint.

Preference order: 1) fn(argv, prog=…) 2) fn(argv) 3) fn() with patched sys.argv

Parameters:
Return type:

None

geoprior.cli._dispatch.public_items(registry, *, family=None)[source]#

Return public registry items filtered by family.

Parameters:
Return type:

list[tuple[str, CommandSpec]]

geoprior.cli._dispatch.alias_map(registry, *, family=None)[source]#

Build alias -> public-name mapping.

Parameters:
Return type:

dict[str, str]

geoprior.cli._dispatch.print_help_table(title, items, *, width=30)[source]#

Print a compact help table.

Parameters:
Return type:

None