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:

• AlreadyAttached – The disk image is already attached on the system.
• InvalidDiskImage – The disk image is not a valid disk image.
• PasswordRequired – A password is required but none was provided.
• PasswordIncorrect – A incorrect password was supplied.

attach(mountpoint=None)

Attaches a disk image.

Parameters:

mountpoint – Optional path where disk image should be mounted.

Returns:

List of mount points.

Raises:

• InvalidOperation – This disk image has already been attached.
• LicenseAgreementNeedsAccepting – The image cannot be automatically mounted due to a license agreement.
• AttachingFailed – Could not attach the disk image or no volumes on mounted disk.

convert(path: str, disk_format: dmglib.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:

• InvalidOperation – The disk image was not attached on the system.
• DetachingFailed – Detaching failed for unknown reasons.

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.

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.

Enumerations

class dmglib.DiskFormat

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'