diskimage¶

Manipulate disk images (vhd, vhdx, iso) on Windows.

Example mounting of the first volume in the disk image on the first available drive letter:

from gonto.diskimage import DiskImage

disk = DiskImage()
disk.open("./mydisk.vhd")
disk.attach()
# Do stuff
disk.detach()
del disk

Example persistent mounting of the first volume of the disk image on a chosen drive letter:

from gonto.diskimage import DiskImage
from gonto.win32.virtdisk import ATTACH_VIRTUAL_DISK_FLAG

disk = DiskImage()
disk.open("./mydisk.vhd")
disk.attach(
    attach_flags=ATTACH_VIRTUAL_DISK_FLAG.NO_DRIVE_LETTER | ATTACH_VIRTUAL_DISK_FLAG.PERMANENT_LIFETIME
)
disk.mount_volume("G:\\")

exception gonto.diskimage.BaseDiskImageError¶: Base error for Gonto’s specific DiskImage errors.

class gonto.diskimage.DiskImage¶

Manipulates a disk image (vhd, vhdx, iso) on Windows.

attach(attach_flags: ATTACH_VIRTUAL_DISK_FLAG = <ATTACH_VIRTUAL_DISK_FLAG.NONE: 0>) → None¶

Attaches a virtual hard disk (VHD) or CD or DVD image file (ISO).

Parameters:

attach_flags – Flags for the attach request (default: win32.virtdisk.ATTACH_VIRTUAL_DISK_FLAG.NONE).

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageAlreadyAttached – If the disk is already attached. Use DiskImage.detach() to detach the disk first if you want to reattach it with different flags.
WindowsError|OSError – If a Win32 error occurs.

create(path: Path | str, size: int, label: str | None = None, device_type: VIRTUAL_STORAGE_TYPE | None = None) → None¶

Create a new disk image containing an NTFS partition.

Parameters:

path – Path to the disk image.
size – Size of the image disk in GiB.
label –
Label of the partition in the disk image (default: None (no label)).

Note

The label name must be 32 char long maximum (it will be truncated if longer).

Only characters allowed in file names are allowed in the label.
device_type – The type of the disk image (default: None (guessed from file extension), currently only VHD is supported).

Raises:

ValueError – If device_type is not DEVICE_VHD.
DiskImageAlreadyOpened – If a virtual disk has already been opened.
VolumeEnumerationTimeout – If volumes are not updated in time after creating the partition.
WindowsError|OSError – If a Win32 error occurs.

detach(detach_flags: DETACH_VIRTUAL_DISK_FLAG = <DETACH_VIRTUAL_DISK_FLAG.NONE: 0>) → None¶

Detaches a virtual hard disk (VHD) or CD or DVD image file (ISO).

Parameters:

detach_flags – Flags for the detach request (default: win32.virtdisk.DETACH_VIRTUAL_DISK_FLAG.NONE).

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
WindowsError|OSError – If a Win32 error occurs.

get_disk_number() → int¶

Get the disk number of the current disk image.

Important

The disk image must be attached!

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
ValueError – If the disk’s physical path has an unexpected format.
WindowsError|OSError – If a Win32 error occurs.

get_image_path() → Path | None¶: Returns the disk image path (if opened).

get_physical_path() → str¶

Retrieves the path to the physical device object that contains a virtual hard disk (VHD) or CD or DVD image file (ISO).

Returns:

The path of the physical device object.

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
WindowsError|OSError – If a Win32 error occurs.

get_volume_mount_point(volume_name: str | None = None) → str | None¶

Get the mount point of the given volume.

Parameters:

volume_name – The name of a volume in the image disk or None for the first volume of the image disk.

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
VolumeNotInDiskImage – If the given volume name does not belong to the current disk image.
WindowsError|OSError – If a Win32 error occurs.

Returns:

The mount point of the volume or None if it is not mounted.

Important

For sake of simplicity, we only handle ONE mount point per volume. If the volume has multiple mount points, only the first one will be returned.

is_volume_in_disk_image(volume_name: str) → bool¶

Checks if the given volume name belongs to the disk image.

Parameters:

volume_name – Path of the volume ("\\?\Volume{GUID}\").

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
WindowsError|OSError – If a Win32 error occurs.

list_volumes() → Iterator[str]¶

List volumes available in the disk image.

Returns:

The available volumes.

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
WindowsError|OSError – If a Win32 error occurs.

mount_volume(mount_point: str, volume_name: str | None = None) → None¶

Mount a volume in the image disk with the given drive letter.

Parameters:

mount_point –
The drive letter or the directory where the volume will be mounted (e.g. "G:\\", "C:\\MyEmptyFolder\\").

Important

The mount path must ends with a trailing backslash (\).
volume_name – The id of the volume to mount (\\?\Volume{GUID}\) or None to mount the first volume of the disk.

Raises:

DiskImageNotOpened – If no virtual disk image was opened using the DiskImage.open() method.
DiskImageNotAttached – If the virtual disk image was not attached using the DiskImage.attach() method.
VolumeNotInDiskImage – If the given volume name does not belong to the current disk image.
WindowsError|OSError – If a Win32 error occurs.

open(path: Path | str, device_type: VIRTUAL_STORAGE_TYPE | None = None, access_mask: VIRTUAL_DISK_ACCESS_MASK = <VIRTUAL_DISK_ACCESS_MASK.ALL: 4128768>, open_flags: OPEN_VIRTUAL_DISK_FLAG = <OPEN_VIRTUAL_DISK_FLAG.NONE: 0>) → None¶

Opens a virtual hard disk (VHD) or CD or DVD image file (ISO) for use.

Parameters:

path – Path to the disk image.
device_type – The type of the disk image (default: None (guessed from file extension)).
access_mask – Bitmask for specifying access rights to a virtual hard disk (default: win32.virtdisk.VIRTUAL_DISK_ACCESS_MASK.ALL).
open_flags – Virtual hard disk open request flags (default: win32.virtdisk.OPEN_VIRTUAL_DISK_FLAG.NONE).

Raises:

DiskImageAlreadyOpened – If a virtual disk has already been opened.
WindowsError|OSError – If a Win32 error occurs.

exception gonto.diskimage.DiskImageAlreadyAttached¶: Trying to attach the disk image whereas it is already attached.

exception gonto.diskimage.DiskImageAlreadyOpened¶: Trying to open a disk image whereas one is already opened in the object.

exception gonto.diskimage.DiskImageNotAttached¶: The operation requires that the disk image was attached.

exception gonto.diskimage.DiskImageNotOpened¶: The operation requires an opened disk image but none was opened.

exception gonto.diskimage.VolumeEnumerationTimeout¶: The volumes cannot be enumerated in time.

exception gonto.diskimage.VolumeNotInDiskImage¶: The given volume does not belong to the open disk image.