pysnap.vbox package

VirtualBox integration package for PySnap.

Submodules

pysnap.vbox.client module

VirtualBox client abstraction built on top of VBoxManage.

class pysnap.vbox.client.RunnerProtocol(*args, **kwargs)

Bases: Protocol

Describe the command runner used by the client.

run(arguments, timeout=None)

Execute a command and return its standard output.

Parameters:

• arguments (Sequence[str]) – Arguments passed to VBoxManage.

• timeout (float | None) – Optional timeout in seconds.

Returns:

Standard output.

Return type:

str

run_streaming(arguments, output_callback)

Execute a command and stream textual output chunks.

Parameters:

• arguments (Sequence[str]) – Arguments passed to VBoxManage.

• output_callback (Callable[[str], None]) – Callback for output chunks.

Returns:

Combined command output.

Return type:

str

class pysnap.vbox.client.SubprocessRunner(executable=None)

Bases: RunnerProtocol

Run VBoxManage commands using subprocess.

Parameters:

executable (str | None)

MACOS_APP_BUNDLE_EXECUTABLE = PosixPath('/Applications/VirtualBox.app/Contents/MacOS/VBoxManage')

WINDOWS_INSTALL_DIRECTORY_ENV_VARS = ('VBOX_MSI_INSTALL_PATH', 'VBOX_INSTALL_PATH')

WINDOWS_DEFAULT_EXECUTABLES = ('C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe', 'C:\\Program Files (x86)\\Oracle\\VirtualBox\\VBoxManage.exe')

run(arguments, timeout=None)

Execute VBoxManage and return standard output.

Parameters:

• arguments (Sequence[str]) – Arguments passed to VBoxManage.

• timeout (float | None) – Optional timeout in seconds.

Returns:

Standard output text.

Raises:

CommandExecutionError – If the command exits unsuccessfully or does not finish before the timeout expires.

Return type:

str

run_streaming(arguments, output_callback)

Execute VBoxManage and stream merged output chunks.

Parameters:

• arguments (Sequence[str]) – Arguments passed to VBoxManage.

• output_callback (Callable[[str], None]) – Callback for output chunks.

Returns:

Combined command output.

Raises:

CommandExecutionError – If the command exits unsuccessfully.

Return type:

str

class pysnap.vbox.client.VBoxManageClient(runner=None)

Bases: object

Expose the subset of VirtualBox operations required by PySnap.

Parameters:

runner (RunnerProtocol | None)

IMPORT_PROGRESS_PATTERN = re.compile('(?P<percent>\\d{1,3})%')

DMI_SYSTEM_VENDOR_KEY = 'VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor'

DMI_SYSTEM_SKU_KEY = 'VBoxInternal/Devices/pcbios/0/Config/DmiSystemSKU'

LIST_COMMAND_TIMEOUT = 15.0

COM_COUNT = 4

DEFAULT_NIC_COUNTS = {'ich9': 36, 'piix3': 8}

NIC_COUNT_PATTERN = re.compile('^Maximum (\\w+) Network Adapter count:\\s*(\\d+)', re.MULTILINE)

COM_RESOURCES = {1: ('0x3F8', '4'), 2: ('0x2F8', '3'), 3: ('0x3E8', '4'), 4: ('0x2E8', '3')}

list_vms()

List all registered VMs.

Returns:

Parsed VM references.

Return type:

list[VMReference]

list_running_vms()

List all currently running VMs.

Returns:

Parsed references for running VMs.

Return type:

list[VMReference]

get_vm_info(vm_name)

Read detailed information about a VM.

Parameters:

vm_name (str) – VM name to inspect.

Returns:

Detailed VM information.

Return type:

VMInfo

add_ssh_forwarding(vm_name, adapter, port, *, running)

Forward a host port on 127.0.0.1 to port 22 of the guest.

Parameters:

• vm_name (str) – VM name.

• adapter (int) – Number of the NAT adapter.

• port (int) – Host port.

• running (bool) – Use controlvm for a running or paused VM instead of modifyvm.

Return type:

None

get_ssh_forwarding(vm_name)

Return the NAT adapter and host port of the PySnap ssh rule.

Parameters:

vm_name (str) – VM name.

Returns:

(adapter, port) or None without such a rule.

Return type:

tuple[int, int] | None

remove_ssh_forwarding(vm_name, adapter)

Delete the PySnap ssh rule of a stopped VM.

Parameters:

• vm_name (str) – VM name.

• adapter (int) – Number of the NAT adapter holding the rule.

Return type:

None

type_on_console(vm_name, text)

Type a line on the screen of a running VM and press Enter.

Ctrl-U first clears a half-typed line. VirtualBox types through US keyboard scan codes, so the guest needs a Latin layout.

Parameters:

• vm_name (str) – VM name.

• text (str) – ASCII text to type.

Return type:

None

delete_metadata(vm_name, key)

Remove one extra data entry of a VM.

Parameters:

• vm_name (str) – VM name.

• key (str) – Extra data key.

Return type:

None

get_vm_hardware(vm_name)

Read the serial ports and network adapters of a VM.

Parameters:

vm_name (str) – VM name to inspect.

Returns:

Settings of COM1-COM4 and of every network adapter the chipset of the VM offers.

Return type:

VMHardware

apply_vm_hardware(vm_name, com_ports, nics)

Change serial ports and network adapters with one modifyvm call.

Parameters:

• vm_name (str) – VM name.

• com_ports (dict[int, ComPortSetting]) – Port numbers mapped to their new settings.

• nics (dict[int, NicSetting]) – Adapter numbers mapped to their new settings.

Return type:

None

set_dmi_system_sku(vm_name, system_sku)

Replace the DMI system SKU of a VM.

Parameters:

• vm_name (str) – VM name.

• system_sku (str) – New DMI system SKU value.

Return type:

None

get_serial_port_configuration(vm_name)

Read the raw UART1 configuration of a VM.

Parameters:

vm_name (str) – VM name to inspect.

Returns:

Parsed UART1 configuration.

Return type:

SerialPortConfiguration

dry_run_import(image_path)

Run an appliance import dry run.

Parameters:

image_path (str) – Appliance path.

Returns:

Import candidates discovered by VirtualBox.

Return type:

list[ImportCandidate]

import_appliance(image_path, candidates, progress_callback=None)

Import an appliance using the supplied dry-run candidates.

Parameters:

• image_path (str) – Appliance path.

• candidates (list[ImportCandidate]) – Normalized import candidates.

• progress_callback (Callable[[int], None] | None) – Optional import progress callback.

Return type:

None

get_current_snapshot_name(vm_name)

Return a snapshot name suitable for linked cloning.

Parameters:

vm_name (str) – VM name to inspect.

Returns:

Snapshot name, if any.

Return type:

str | None

take_snapshot(vm_name, snapshot_name)

Create a snapshot for a VM.

Parameters:

• vm_name (str) – VM name.

• snapshot_name (str) – Snapshot name to create.

Return type:

None

clone_linked(base_vm, clone_vm, group, snapshot_name)

Create and register a linked clone.

Parameters:

• base_vm (str) – Source VM name.

• clone_vm (str) – Clone VM name.

• group (str) – Group assigned to the clone.

• snapshot_name (str) – Snapshot used as clone source.

Return type:

None

start_vm_headless(vm_name)

Start a VM in headless mode.

Parameters:

vm_name (str) – VM name.

Return type:

None

stop_vm_acpi(vm_name)

Request a graceful ACPI shutdown for a running VM.

Parameters:

vm_name (str) – VM name.

Return type:

None

pause_vm(vm_name)

Pause a running VM; it stays in memory.

Parameters:

vm_name (str) – VM name.

Return type:

None

resume_vm(vm_name)

Resume a paused VM.

Parameters:

vm_name (str) – VM name.

Return type:

None

get_vm_state(vm_name)

Return the current VirtualBox runtime state of a VM.

Parameters:

vm_name (str) – VM name.

Returns:

Raw VirtualBox state string.

Return type:

str

configure_serial_port(vm_name, serial_port)

Configure UART1 as a TCP server on the provided host port.

Parameters:

• vm_name (str) – VM name.

• serial_port (int) – Host TCP port exposed through UART1.

Raises:

PySnapError – If the port number is unsupported.

Return type:

None

configure_internal_networks(vm_name, networks, preserve_primary_nat=False)

Configure clone networking according to the requested layout.

Parameters:

• vm_name (str) – VM name.

• networks (Sequence[str]) – Internal network names.

• preserve_primary_nat (bool) – Keep NIC1 on NAT and place networks on NIC2-NIC4 without disabling omitted adapters.

Raises:

PySnapError – If more than three networks are provided.

Return type:

None

set_metadata(vm_name, metadata)

Persist PySnap metadata in VirtualBox extra data.

Parameters:

• vm_name (str) – VM name.

• metadata (dict[str, str]) – Extra data entries to set.

Return type:

None

configure_dmi_system_information(vm_name, system_vendor, system_sku)

Persist DMI system information for one VM.

Parameters:

• vm_name (str) – VM name.

• system_vendor (str) – DMI system vendor value.

• system_sku (str) – DMI system SKU value.

Return type:

None

get_metadata(vm_name)

Read all extra data entries for a VM.

Parameters:

vm_name (str) – VM name.

Returns:

Extra data mapping.

Return type:

dict[str, str]

delete_vm(vm_name)

Delete and unregister a VM.

Parameters:

vm_name (str) – VM name.

Return type:

None

pysnap.vbox.parsers module

Parsers for VBoxManage command output.

pysnap.vbox.parsers.parse_list_vms(output)

Parse VBoxManage list vms output.

Parameters:

output (str) – Raw command output.

Returns:

Parsed VM references.

Return type:

list[VMReference]

pysnap.vbox.parsers.parse_machine_readable(output)

Parse VBoxManage --machinereadable output.

Parameters:

output (str) – Raw command output.

Returns:

Mapping of property names to values.

Return type:

dict[str, str]

pysnap.vbox.parsers.parse_extra_data(output)

Parse VBoxManage getextradata ... enumerate output.

Parameters:

output (str) – Raw command output.

Returns:

Mapping of extra data keys to values.

Return type:

dict[str, str]

pysnap.vbox.parsers.parse_snapshot_names(properties)

Extract snapshot names from machine-readable VM properties.

Parameters:

properties (dict[str, str]) – Parsed machine-readable VM properties.

Returns:

Snapshot names ordered with the current snapshot first when possible.

Return type:

list[str]

pysnap.vbox.parsers.parse_import_candidates(output)

Parse VBoxManage import --dry-run output.

Parameters:

output (str) – Raw dry-run output.

Returns:

Appliance VM candidates discovered in the dry run.

Return type:

list[ImportCandidate]

pysnap.vbox.parsers.split_groups(raw_groups)

Split a machine-readable group list.

Parameters:

raw_groups (str) – Raw groups property value.

Returns:

Tuple of group names.

Return type:

tuple[str, …]