numberlink.cli

Command line interface for the numberlink package.

This module provides a small command line utility that can register the environment, print textual representations of puzzle boards, list bundled level identifiers, and open an interactive viewer. The primary entry points are build_parser() for constructing the argument parser and main() for the console entry point.

The subcommand handlers are implemented as handle_register(), handle_viewer(), handle_board(), and handle_levels(). Use load_grid_from_file() to load a grid from a filesystem path and load_bridges() to parse an optional JSON list of bridge coordinates.

See also numberlink.config.VariantConfig for variant options and numberlink.env.NumberLinkRGBEnv for environment details used by the viewer and board commands.

Module Contents

Functions

build_parser	Build the top level command line argument parser.
load_grid_from_file	Load a grid specification from disk using numberlink.levels.load_level_from_file().
load_solution_for_grid	Load an optional solution adjacent to a grid file.
load_bridges	Load bridge coordinates from a JSON file.
build_variant_from_args	Create a numberlink.config.VariantConfig from CLI overrides.
build_render_config_from_args	Create a numberlink.config.RenderConfig from CLI arguments when overrides are present.
handle_register	Handle the register subcommand.
handle_viewer	Handle the viewer subcommand.
handle_board	Handle the board subcommand.
handle_levels	Handle the levels subcommand and print bundled level identifiers.
main	Command line entry point for the package.

API

numberlink.cli.build_parser() → argparse.ArgumentParser

Build the top level command line argument parser.

The returned argparse.ArgumentParser is configured with the following subcommands and their handlers handle_register(), handle_viewer(), handle_board(), and handle_levels().

Returns:

Configured argument parser ready to parse command line arguments.

Return type:

argparse.ArgumentParser

numberlink.cli.load_grid_from_file(path_obj: pathlib.Path) → collections.abc.Sequence[str]

Load a grid specification from disk using numberlink.levels.load_level_from_file().

Return the list of row strings stored in the loaded numberlink.levels.Level.

Parameters:

path_obj – Filesystem path to a grid file.

Returns:

List of row strings read from the file.

Raises:

ValueError – When the file contains no non empty rows.

numberlink.cli.load_solution_for_grid(path_obj: pathlib.Path) → list[list[Coord]] | None

Load an optional solution adjacent to a grid file.

Use numberlink.levels.load_level_from_file() to load the grid and return the numberlink.levels.Level.solution value when present, None when no solution was given with the grid.

Parameters:

path_obj – Filesystem path to the grid file.

Returns:

Solution paths or None when not available.

numberlink.cli.load_bridges(bridges_path: pathlib.Path | None) → collections.abc.Sequence[Coord] | None

Load bridge coordinates from a JSON file.

Return a sequence of (row, column) pairs. The JSON file must contain a top level list. Each entry must be a two element sequence representing a row and column index. Strings and byte sequences are rejected. The function converts numeric values to Python integers and returns None when bridges_path is None.

Parameters:

bridges_path – Path to a JSON file or None to indicate no bridges should be loaded.

Returns:

Sequence of coordinate pairs or None when no file was provided.

Return type:

collections.abc.Sequence[tuple[int, int]] or None

Raises:

ValueError – If any JSON entry is not a two element sequence of numeric values.

numberlink.cli.build_variant_from_args(default_variant: numberlink.config.VariantConfig, must_fill: bool | None, allow_diagonal: bool | None, bridges_enabled: bool | None, cell_switch: bool | None) → numberlink.config.VariantConfig

Create a numberlink.config.VariantConfig from CLI overrides.

For each override parameter, when the provided value is not None the returned variant uses that value. When the provided value is None the corresponding attribute from default_variant is preserved.

Parameters:

• default_variant – Default variant to use for attributes that are not overridden.

• must_fill – Override for the must_fill option when not None.

• allow_diagonal – Override for the allow_diagonal option when not None.

• bridges_enabled – Override for the bridges_enabled option when not None.

• cell_switch – Override for the cell_switching_mode option when not None.

Returns:

New numberlink.config.VariantConfig instance with the requested overrides applied.

Return type:

numberlink.config.VariantConfig

numberlink.cli.build_render_config_from_args(args: argparse.Namespace) → numberlink.config.RenderConfig | None

Create a numberlink.config.RenderConfig from CLI arguments when overrides are present.

Return None when no render config arguments were provided, allowing the environment to use its default configuration. When any render config option is specified, build and return a new numberlink.config.RenderConfig with overrides applied.

Parameters:

args – Parsed CLI arguments containing optional render config fields.

Returns:

New numberlink.config.RenderConfig instance when overrides are present, otherwise None.

Return type:

RenderConfig or None

numberlink.cli.handle_register(args: argparse.Namespace) → int

Handle the register subcommand.

This function calls numberlink.registration.register_numberlink_v0() to register the environment id with the Gymnasium registry. When the args.quiet flag is not set a brief confirmation message is emitted to standard output. The function returns an exit code suitable for a console entry point.

Parameters:

args – Parsed arguments from build_parser() with an attribute quiet of type bool.

Returns:

Process exit code. 0 indicates success.

Return type:

int

numberlink.cli.handle_viewer(args: argparse.Namespace) → int

Handle the viewer subcommand.

Open an interactive viewer when appropriate. The function loads an optional grid using load_grid_from_file() and optional bridge coordinates using load_bridges(). It builds a numberlink.config.VariantConfig from CLI overrides using build_variant_from_args(). It creates a numberlink.env.NumberLinkRGBEnv instance for the requested configuration and performs an initial numberlink.env.NumberLinkRGBEnv.reset().

When the --apply-solution flag is provided and a stored solution is available the solution is applied by issuing calls to numberlink.env.NumberLinkRGBEnv.step(). When --render-mode is ansi the textual representation from numberlink.env.NumberLinkRGBEnv._render_text() is printed. For other render modes a numberlink.viewer.NumberLinkViewer is constructed and its numberlink.viewer.NumberLinkViewer.loop() method is invoked.

The environment is always closed by calling numberlink.env.NumberLinkRGBEnv.close() in a finally block.

Parameters:

args – Parsed arguments from build_parser().

Returns:

Process exit code. 0 indicates success.

Return type:

int

numberlink.cli.handle_board(args: argparse.Namespace) → int

Handle the board subcommand.

Print a textual rendering of a requested level. The function behaves similarly to handle_viewer() for argument parsing and variant construction. It creates a numberlink.env.NumberLinkRGBEnv with render_mode set to ansi and prints the textual board returned by numberlink.env.NumberLinkRGBEnv._render_text() after calling numberlink.env.NumberLinkRGBEnv.reset().

When the --apply-solution flag is provided the function attempts to retrieve a stored solution via numberlink.env.NumberLinkRGBEnv.get_solution(). If a solution is found it is applied stepwise using numberlink.env.NumberLinkRGBEnv.step() and the resulting board is printed.

The environment is closed by calling numberlink.env.NumberLinkRGBEnv.close() in a finally block.

Parameters:

args – Parsed arguments from build_parser().

Returns:

Process exit code. 0 indicates success.

Return type:

int

numberlink.cli.handle_levels(args: argparse.Namespace) → int

Handle the levels subcommand and print bundled level identifiers.

The function enumerates the keys of numberlink.levels.LEVELS and optionally filters them by substring when args.contains is set.

Parameters:

args – Parsed arguments from build_parser() with an optional attribute contains used for substring filtering.

Returns:

Process exit code. 0 indicates success.

Return type:

int

numberlink.cli.main(argv: collections.abc.Sequence[str] | None = None) → int

Command line entry point for the package.

The function constructs the parser via build_parser(), parses the provided argument list, and dispatches to the handler bound on the chosen subparser. When no subcommand is provided the parser help message is printed and the function returns 0.

Parameters:

argv – Optional sequence of arguments to parse. When None the system argv is used by argparse.

Returns:

Process exit code produced by the selected subcommand handler or 0 when no command was requested.

Return type:

int