Documentation for the core tools module in the tools package (Tools/core.py)

This is the tools package for DDRescue-GUI.

class ddrescue_gui.Tools.core.AuthWindow

A simple authentication dialog that is used when elevated privileges are required. Until version 2.0.0, this was used to start the GUI, but since that release, privileges are only escalated when required to improve security.

This is used to pre-authenticate on macOS if needed, before running a privileged task with sudo.

bind_events()

Bind all events for AuthenticationWindow

create_buttons()

Create all buttons for AuthenticationWindow

create_other_widgets()

Create all other widgets for AuthenticationWindow

create_text()

Create all text items for AuthenticationWindow.

on_auth_attempt(event=None)

Check the password is correct. If not, then either warn the user to try again. If so, exit as all we need to do is pre-authenticate on macOS.

Args:

event. The event object passed by wxpython (optional).

on_exit(event=None)

Close AuthWindow() and exit

run()

Preauthenticates macOS users with the auth dialog. If we are already pre-authenticated, just return immediately.

setup_sizers()

Setup sizers for AuthWindow

test_auth()

Check if we have cached authentication.

Returns:

bool. True = We have cached authentication.

False = We don’t.

ddrescue_gui.Tools.core.change_units(number_to_change, current_unit, required_unit)

Convert data so it uses the correct unit of measurement.

Args:

number_to_change (int). The number we wish to change the units

for.

current_unit (string). The current unit of this number. required_unit (string). The required unit for this number.

Returns:

tuple(int, string).

1st element: The number’s value in its new unit. 2nd element: The new unit.

ddrescue_gui.Tools.core.create_unique_key(dictionary, data, length)

Create a unique dictionary key.

The unique key is created by adding a number on the the end of the given data, while keeping it at the correct length. The key will also start with ‘…’ if the data was longer than the specified length.

Args:

dictionary (dict). The dictionary that the key will be stored

in. This is needed to check the uniqueness of the keys - we will keep generating new ones until we arrive at a unique one.

data (string). The data that we need to create a key for.

length (int). The maximum length of the key.

Returns:

string. The unique key.

ddrescue_gui.Tools.core.determine_ddrescue_version()

Used to determine the version of ddrescue installed on the system, or (for macOS and Windows) bundled with the GUI.

Handles -pre and -rc versions too, by stripping that information from the version string and warning the user (not doing so would cause errors in other parts of DDRescue-GUI).

Returns:

string. The ddrescue version present on the system.

ddrescue_gui.Tools.core.determine_getdevinfo_version()

Used to determine the version of getdevinfo installed on the system, or (for macOS and Windows) bundled with the GUI.

Returns:

string. The getdevinfo version present on the system.

ddrescue_gui.Tools.core.emergency_exit(msg)

Handle emergency exits. Warn the user, log the error, save the log file, and exit to terminal with the given message.

Args:

msg (string). A description of the unrecoverable error that

was encountered.

Warning

Calling this function will exit DDRescue-GUI immediately after warning the user to save a log file.

ddrescue_gui.Tools.core.find_ddrescue()

Attempts to find GNU ddrescue, and ends the program if it couldn’t be found.

ddrescue_gui.Tools.core.get_helper(cmd)

Figure out which helper script to use for this command.

Args:

cmd (string). The command(s) about to be run.

Returns:

string. “pkexec” + <the helper script needed>

• the command(s) to run.

ddrescue_gui.Tools.core.get_mount_point(partition)

Returns the mountpoint of the given partition, if any.

Args:

partition (string). The partition to find the mount point of.

Returns:

Multiple types.

String: The mount point of the partition, if

it was mounted.

None: Returned when mount point was not

found.

ddrescue_gui.Tools.core.is_mounted(partition, mount_point=None)

Checks if the given partition is mounted.

Args:

partition (string). The partition to check.

mount_point[=None] (string). If specified, check that partition

is mounted at this mount point. Otherwise, just check that it is mounted somewhere.

Returns:

bool.

True = The partition is mounted. False = The partition is not mounted.

ddrescue_gui.Tools.core.is_partition(disk, disk_info)

Check if the given disk is a partition.

Args:

disk (string). The disk to check. disk_info (dict). The disk info dictionary containing information gathered with GetDevInfo.

Returns:

boolean.

True - The disk is a partition. False - The disk is not a partition.

ddrescue_gui.Tools.core.mount_disk(partition, mount_point, options='')

Mounts the given partition at the given mount point.

Args:

partition (string). The partition to mount. mount_point (string). The path where the partition is to be mounted.

options[=””] (string). Any options to pass to the mount command.

If not specified, no options are passed.

Returns:

Multiple types.

boolean False: If another filesystem was in the way at

the specified mount point and it could not be unmounted.

int.

0 - Success, or partition already mounted at

that mount point.

Anything else - Error, return value from mount command.

ddrescue_gui.Tools.core.read(cmd, testing=False)

Read the cmd’s output character by character. Also make sure everything is converted to unicode. Break lines by the newline and (carriage return) characters. Also handle null characters by removing them from the output.

Args:

cmd. The subprocess object that represents the command.

testing[=False]. Used during unit tests, disables some of the

cleanup done to the output. Do not use in production.

Returns:

list. A list where each line in the (cleaned up)

output is a new item in the list.

ddrescue_gui.Tools.core.send_notification(msg)

Send a notification, with the given message.

Args:

msg (string). The message to display in the notification.

ddrescue_gui.Tools.core.start_process(cmd, return_output=False, privileged=False)

Start a given process, and return the output and return value if needed.

Args:

cmd (string). The command(s) to run.

return_output[=False] Whether to return the output or not. If not

specified, the default is False.

privileged[=False] Whether to execute the command(s) with

elevated privileges or not. If not specified the default is False.

Returns:

May return multiple types:

int. If return_output is not specified or set to

False, return the return value of the command(s).

tuple(int, string). Otherwise, return a tuple with the return value,

and then a string with new lines delimited by newline characters.

ddrescue_gui.Tools.core.unmount_disk(disk)

Unmount the given disk.

Args:

disk (string). The disk to unmount.

Returns:

int.

0 - Success, or disk not mounted. Anything else - Error, return value from unmount command.