pysnap.cli package

CLI helpers for PySnap.

Submodules

pysnap.cli.app module

Command line interface for PySnap.

exception pysnap.cli.app.ParserExit(status=0)[source]

Bases: Exception

Represent a controlled parser exit.

Parameters:

status (int)

Return type:

None

class pysnap.cli.app.HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]

Bases: RawDescriptionHelpFormatter

Wrap help paragraphs and keep indented lines such as examples.

Descriptions and epilogs are split into blank-line separated blocks. A block without indented lines is wrapped as one paragraph; a block with indented lines (an example list or an option table) is kept as written.

class pysnap.cli.app.CliArgumentParser(*args, stdout=None, stderr=None, **kwargs)[source]

Bases: ArgumentParser

Route argparse output through caller-provided streams.

Parameters:

  • args (object)

  • stdout (TextIO | None)

  • stderr (TextIO | None)

  • kwargs (object)

exit(status=0, message=None)[source]

Raise a controlled parser exit instead of terminating the process.

Parameters:

  • status (int) – Exit status code.

  • message (str | None) – Optional exit message.

Raises:

ParserExit – Always raised with the requested status.

Return type:

None

pysnap.cli.app.build_root_parser(stdout=None, stderr=None)[source]

Build the root CLI parser used for help output.

Parameters:

  • stdout (TextIO | None) – Stream used for help output.

  • stderr (TextIO | None) – Stream used for parser errors.

Returns:

Configured argument parser.

Return type:

CliArgumentParser

pysnap.cli.app.run_cli(argv=None, service=None, stdout=None, stderr=None, stdin=None)[source]

Execute the CLI.

Parameters:

  • argv (Sequence[str] | None) – Command line arguments without the executable name.

  • service (PySnapService | None) – Optional application service.

  • stdout (TextIO | None) – Output stream for regular messages.

  • stderr (TextIO | None) – Output stream for errors.

  • stdin (TextIO | None) – Input stream for interactive confirmations.

Returns:

Process exit code.

Return type:

int

pysnap.cli.app.main(argv=None)[source]

Program entry point.

Parameters:

argv (Sequence[str] | None) – Optional command line arguments.

Returns:

Process exit code.

Return type:

int

pysnap.cli.formatters module

Output formatters used by the PySnap CLI.

class pysnap.cli.formatters.ImportProgressBar(stream, label='Importing', width=32, current_percent=0, started=False)[source]

Bases: object

Render a live import progress bar to a text stream.

Parameters:

  • stream (TextIO)

  • label (str)

  • width (int)

  • current_percent (int)

  • started (bool)

stream: TextIO
label: str = 'Importing'
width: int = 32
current_percent: int = 0
started: bool = False
update(percent)[source]

Update the progress bar.

Parameters:

percent (int) – Percentage reported by VBoxManage.

Return type:

None

finish()[source]

Terminate the progress-bar line when it was shown.

Return type:

None

pysnap.cli.formatters.format_groups(groups)[source]

Format a group listing for terminal output.

Parameters:

groups (list[VMGroup]) – Group objects to format.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.formatters.format_vm_info(vm_info, access=None)[source]

Format one VM description for terminal output.

Parameters:

  • vm_info (VMInfo) – VM information to format.

  • access (AccessInfo | None) – How PySnap reaches the guest, if known.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.formatters.format_access(access)[source]

Describe how PySnap reaches a guest in one line.

Parameters:

access (AccessInfo) – Access description.

Returns:

For example ssh root@127.0.0.1:2222 (default).

Return type:

str

pysnap.cli.formatters.format_vm_settings(result)[source]

Format the serial ports and network adapters of a VM.

Parameters:

result (VMSettingsResult) – Result of pysnap set.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.formatters.format_import_result(imported_vms)[source]

Format the result of an appliance import.

Parameters:

imported_vms (list[VMInfo]) – Imported VM information objects.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.formatters.format_integration_test_result(result)[source]

Format the result of a completed integration test run.

Parameters:

result (IntegrationTestResult) – Integration test result to render.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.formatters.format_monitor_records(records)[source]

Format compact runtime records for the monitor command.

Parameters:

records (list[VMMonitorRecord]) – Monitor records to format.

Returns:

Human-readable text output.

Return type:

str

pysnap.cli.report module

pysnap report subcommands.

pysnap.cli.report.build_report_parser(stdout, stderr)[source]

Build the pysnap report parser with its subcommands.

Parameters:

  • stdout (TextIO) – Stream used for help output.

  • stderr (TextIO) – Stream used for parser errors.

Returns:

Configured parser.

Return type:

ArgumentParser

pysnap.cli.report.run_report_command(arguments, service, stdout, stderr)[source]

Run pysnap report.

Parameters:

  • arguments (Sequence[str]) – Arguments after report.

  • service (PySnapService) – Application service.

  • stdout (TextIO) – Output stream.

  • stderr (TextIO) – Error stream.

Returns:

Process exit code.

Return type:

int

pysnap.cli.report.format_compare_result(result)[source]

Render a pairwise comparison.

Pairs with signals come first with only the signals found; pairs without signals take one line each.

Parameters:

result (CompareResult) – Comparison result.

Returns:

Multi-line human-readable text.

Return type:

str

pysnap.cli.report.format_check_result(result, transcript)[source]

Render the per-item results and the grade.

Parameters:

  • result (CheckResult) – Graded check result.

  • transcript (Transcript) – Rendered report, used to show what matched.

Returns:

Multi-line human-readable text.

Return type:

str

pysnap.cli.report.format_report_stats(stats)[source]

Render the report information block.

Parameters:

stats (ReportStats) – Report statistics.

Returns:

Multi-line human-readable text.

Return type:

str

pysnap.cli.report.format_transcript(transcript, *, color)[source]

Render transcript lines, highlighting prompts and commands.

Parameters:

  • transcript (Transcript) – Rendered session.

  • color (bool) – Whether to emit ANSI styles.

Returns:

Output lines.

Return type:

list[str]

pysnap.cli.report.format_command_list(commands)[source]

Render the numbered list of entered commands.

Parameters:

commands (Sequence[CommandRecord]) – Commands in recording order.

Returns:

One line per command with its recording time.

Return type:

str