API documentation

The most straight-forward way to use the functionality this package provides is simply to use a context manager:

dmglib.attachedDiskImage(path: str, keyphrase=None)

Context manager to work with a disk image.

The context manager returns the list of mount points of the attached volumes. There is always at least one mount point available, otherwise attaching fails. The caller needs to catch exceptions (see documentation for the DiskImage class), or call the appropriate methods beforehand (dmg_is_encrypted(), …).

Example:

with dmg.attachedDiskImage('path/to/disk_image.dmg',
                           keyphrase='sample') as mount_points:
    print(mount_points)

Apart from the context manager, you may also explicitly use the DiskImage class:

class dmglib.DiskImage(path, keyphrase=None)

Class representing macOS Disk Images (.dmg) files.

Initialize a disk image object. Note: Simply constructing the object does not attach the DMG. Use the DiskImage.attach() method for that.

Parameters:
  • path – The path to the disk image

  • keyphrase – Optional argument for password protected images

Raises:
attach(mountpoint=None)

Attaches a disk image.

Parameters:

mountpoint – Optional path where disk image should be mounted.

Returns:

List of mount points.

Raises:
convert(path: str, disk_format: DiskFormat) str

Converts a disk image to a different format.

Parameters:
  • path – The path where to store the converted disk image.

  • disk_format – One of the hdiutil supported disk image formats, see DiskFormat

Returns:

The filepath where the converted disk image was stored. Note that this may differ from path in case the correct file extension for the chosen disk format differs from the file extension provided as part of path.

Raises:

ConversionFailed – hdiutil could not convert the disk image to the specified format.

detach(force=True)

Detaches a disk image.

Parameters:

force – ignore open files on mounted volumes. See man 1 hdiutil.

Raises:
has_license_agreement() bool

Checks whether the disk image has an attached license agreement.

DMGs with license agreements cannot be attached using this package.

Standalone functions

dmglib.dmg_is_valid(path: str) bool

Checks the validity of the supplied disk image.

A disk image is valid according to this logic, if it is either not encrypted and valid according to hdiutil, or encrypted according to hdiutil.

dmglib.attached_images() list

Obtain a list of paths to disk images that are currently attached.

dmglib.dmg_already_attached(path: str) bool

Checks whether the disk image at the supplied path has already been attached.

Querying the system for further information about already attached images fails with a resource exhaustion error message.

dmglib.dmg_is_encrypted(path: str) bool

Checks whether DMG at the supplied path is password protected.

dmglib.dmg_check_keyphrase(path: str, keyphrase: str) bool

Checks the keyphrase for the disk image at the supplied path.

Note

This function assumes the DiskImage is encrypted and raises an exception if it is not.

Parameters:
  • path – path to disk image for which to check the keyphrase

  • keyphrase – keyphrase to check

Raises:

InvalidOperation – the disk image was not encrypted.

dmglib.dmg_get_mountpoints(path: str) dict

Returns mountpoints of the already attached dmg.

Parameters:

path – path to the already attached disk image.

Returns:

Dict with mountpoints.

Raises:

InvalidOperation – if image is not already attached.

dmglib.dmg_detach_already_attached(path: str, force=True)

Detaches a disk image without DiskImage object, e.g. for creating it.

Parameters:
  • path – path to the disk image

  • force – ignore open files on mounted volumes. See man 1 hdiutil.

Raises:
dmglib.dmg_create_blank(path: str, disk_type: DiskCreateBlankFormat = None, fs_type: FsFormat = None, size=None, rename_sparse=False)

Creates blank DMG. Note: Doesn’t construct the DiskImage object.

Parameters:
  • path – The path to the disk image

  • disk_type – Optional argument, specifies disk type for blank images

  • fs_type – Optional argument, specifies filesystem type for blank images

  • size – Optional argument, specifies size for blank images

  • rename_sparse – Optional argument, if true renames ‘.dmg.sparseimage’ to ‘.dmg’, for sparseimages

Raises:

CreatingFailed – Error while creating blank disk images

Exceptions

exception dmglib.InvalidDiskImage

The disk image is deemed invalid and therefore cannot be attached.

exception dmglib.InvalidOperation

An invalid operation was performed by the user.

Examples include trying to detach a dmg that was never attached or trying to attach a disk image twice.

exception dmglib.ConversionFailed

Error to indicate that conversion failed

exception dmglib.AttachingFailed

Attaching failed for unknown reasons.

exception dmglib.DetachingFailed

Error to indicate a volume could not be detached successfully.

exception dmglib.AlreadyAttached

The disk image has already been attached previously.

exception dmglib.PasswordRequired

No password was required even though one was required.

exception dmglib.PasswordIncorrect

An incorrect password was supplied for the disk image.

exception dmglib.LicenseAgreementNeedsAccepting

Error indicating that a license agreement needs accepting.

exception dmglib.CreatingFailed

Error to indicate an image could not be created successfully.

Enumerations

class dmglib.DiskFormat(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Supported disk image formats for convert verb.

COMPRESSED = 'UDZO'
COMPRESSED_ADC = 'UDCO'
COMPRESSED_BZIP2 = 'UDBZ'
COMPRESSED_LZFSE = 'UDFO'
COMPRESSED_LZMA = 'ULMO'
DISK_COPY = 'DC42'
ENTIRE_DEVICE = 'UFBI'
IPOD_IMAGE = 'IPOD'
NDIF_COMPRESSED = 'ROCo'
NDIF_KEN_CODE = 'Rken'
NDIF_READ_ONLY = 'Rdxx'
NDIF_READ_WRITE = 'RdWr'
OPTICAL_MASTER = 'UDTO'
READ_ONLY = 'UDRO'
READ_WRITE = 'UDRW'
SPARSE = 'UDSP'
SPARSE_BUNDLE = 'UDSB'
UDIF_STUB = 'UDxx'
class dmglib.DiskCreateBlankFormat(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Supported disk image formats for create verb (blank images).

OPTICAL_MASTER = 'UDTO'
READ_WRITE_IMAGE = 'UDIF'
SPARSEBUNDLE_IMAGE = 'SPARSEBUNDLE'
SPARSE_IMAGE = 'SPARSE'
class dmglib.FsFormat(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Supported filesystem formats.

APFS = 'APFS'
APFS_CASE = 'Case-sensitive APFS'
EXFAT = 'ExFAT'
MAC_OS_EXTENDED = 'HFS+'
MAC_OS_EXTENDED_CASE = 'Case-sensitive HFS+'
MAC_OS_EXTENDED_CASE_JOUR = 'Case-sensitive Journaled HFS+'
MAC_OS_EXTENDED_JOUR = 'Journaled HFS+'
MS_DOS_FAT = 'MS-DOS'
MS_DOS_FAT12 = 'MS-DOS FAT12'
MS_DOS_FAT16 = 'MS-DOS FAT16'
MS_DOS_FAT32 = 'MS-DOS FAT32'
UNIVERSAL_DISK = 'UDF'