Drive

class Drive(*args, **kwargs)

GDrive represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media. For example, an optical disc drive, or a USB flash drive.

GDrive is a container class for Volume objects that stem from the same piece of media. As such, GDrive abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media.

If the GDrive reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise.

GDrive supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a GDrive may vary according to implementation. To choose the correct verbs in e.g. a file manager, use get_start_stop_type.

For porting from GnomeVFS note that there is no equivalent of GDrive in that API.

Methods

class Drive

can_eject() → bool

Checks if a drive can be ejected.

can_poll_for_media() → bool

Checks if a drive can be polled for media changes.

can_start() → bool

Checks if a drive can be started.

Added in version 2.22.

can_start_degraded() → bool

Checks if a drive can be started degraded.

Added in version 2.22.

can_stop() → bool

Checks if a drive can be stopped.

Added in version 2.22.

async eject(self, flags: MountUnmountFlags) → bool

This is the awaitable version of eject().

Deprecated since version 2.22: Use eject_with_operation() instead.

Parameters:

flags – flags affecting the unmount if required for eject

eject(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously ejects a drive.

When the operation is finished, callback will be called. You can then call eject_finish() to obtain the result of the operation.

Deprecated since version 2.22: Use eject_with_operation() instead.

Parameters:

• flags – flags affecting the unmount if required for eject

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

eject_finish(result: AsyncResult) → bool

Finishes ejecting a drive.

Deprecated since version 2.22: Use eject_with_operation_finish() instead.

Parameters:

result – a AsyncResult.

async eject_with_operation(self, flags: MountUnmountFlags, mount_operation: MountOperation | None = None) → bool

This is the awaitable version of eject_with_operation().

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for eject

• mount_operation – a MountOperation or None to avoid user interaction.

eject_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Ejects a drive. This is an asynchronous operation, and is finished by calling eject_with_operation_finish() with the drive and AsyncResult data returned in the callback.

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for eject

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data passed to callback.

eject_with_operation_finish(result: AsyncResult) → bool

Finishes ejecting a drive. If any errors occurred during the operation, error will be set to contain the errors and False will be returned.

Added in version 2.22.

Parameters:

result – a AsyncResult.

enumerate_identifiers() → list[str]

Gets the kinds of identifiers that drive has. Use get_identifier() to obtain the identifiers themselves.

get_icon() → Icon

Gets the icon for drive.

get_identifier(kind: str) → str | None

Gets the identifier of the given kind for drive. The only identifier currently available is DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.

Parameters:

kind – the kind of identifier to return

get_name() → str

Gets the name of drive.

get_sort_key() → str | None

Gets the sort key for drive, if any.

Added in version 2.32.

get_start_stop_type() → DriveStartStopType

Gets a hint about how a drive can be started/stopped.

Added in version 2.22.

get_symbolic_icon() → Icon

Gets the icon for drive.

Added in version 2.34.

get_volumes() → list[Volume]

Get a list of mountable volumes for drive.

The returned list should be freed with free(), after its elements have been unreffed with unref().

has_media() → bool

Checks if the drive has media. Note that the OS may not be polling the drive for media changes; see is_media_check_automatic() for more details.

has_volumes() → bool

Check if drive has any mountable volumes.

is_media_check_automatic() → bool

Checks if drive is capable of automatically detecting media changes.

is_media_removable() → bool

Checks if the drive supports removable media.

is_removable() → bool

Checks if the Drive and/or its media is considered removable by the user. See is_media_removable().

Added in version 2.50.

async poll_for_media(self) → bool

This is the awaitable version of poll_for_media().

poll_for_media(cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously polls drive to see if media has been inserted or removed.

When the operation is finished, callback will be called. You can then call poll_for_media_finish() to obtain the result of the operation.

Parameters:

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

poll_for_media_finish(result: AsyncResult) → bool

Finishes an operation started with poll_for_media() on a drive.

Parameters:

result – a AsyncResult.

async start(self, flags: DriveStartFlags, mount_operation: MountOperation | None = None) → bool

This is the awaitable version of start().

Added in version 2.22.

Parameters:

• flags – flags affecting the start operation.

• mount_operation – a MountOperation or None to avoid user interaction.

start(flags: DriveStartFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously starts a drive.

When the operation is finished, callback will be called. You can then call start_finish() to obtain the result of the operation.

Added in version 2.22.

Parameters:

• flags – flags affecting the start operation.

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

start_finish(result: AsyncResult) → bool

Finishes starting a drive.

Added in version 2.22.

Parameters:

result – a AsyncResult.

async stop(self, flags: MountUnmountFlags, mount_operation: MountOperation | None = None) → bool

This is the awaitable version of stop().

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for stopping.

• mount_operation – a MountOperation or None to avoid user interaction.

stop(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously stops a drive.

When the operation is finished, callback will be called. You can then call stop_finish() to obtain the result of the operation.

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for stopping.

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

stop_finish(result: AsyncResult) → bool

Finishes stopping a drive.

Added in version 2.22.

Parameters:

result – a AsyncResult.

Signals

class Drive.signals

changed() → None

The type of the None singleton.

disconnected() → None

The type of the None singleton.

eject_button() → None

The type of the None singleton.

stop_button() → None

The type of the None singleton.

Added in version 2.22.

Virtual Methods

class Drive

do_can_eject() → bool

Checks if a drive can be ejected.

do_can_poll_for_media() → bool

Checks if a drive can be polled for media changes.

do_can_start() → bool

Checks if a drive can be started.

Added in version 2.22.

do_can_start_degraded() → bool

Checks if a drive can be started degraded.

Added in version 2.22.

do_can_stop() → bool

Checks if a drive can be stopped.

Added in version 2.22.

do_changed() → None

The type of the None singleton.

do_disconnected() → None

The type of the None singleton.

do_eject(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously ejects a drive.

When the operation is finished, callback will be called. You can then call eject_finish() to obtain the result of the operation.

Deprecated since version 2.22: Use eject_with_operation() instead.

Parameters:

• flags – flags affecting the unmount if required for eject

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

do_eject_button() → None

The type of the None singleton.

do_eject_finish(result: AsyncResult) → bool

Finishes ejecting a drive.

Deprecated since version 2.22: Use eject_with_operation_finish() instead.

Parameters:

result – a AsyncResult.

do_eject_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Ejects a drive. This is an asynchronous operation, and is finished by calling eject_with_operation_finish() with the drive and AsyncResult data returned in the callback.

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for eject

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data passed to callback.

do_eject_with_operation_finish(result: AsyncResult) → bool

Finishes ejecting a drive. If any errors occurred during the operation, error will be set to contain the errors and False will be returned.

Added in version 2.22.

Parameters:

result – a AsyncResult.

do_enumerate_identifiers() → list[str]

Gets the kinds of identifiers that drive has. Use get_identifier() to obtain the identifiers themselves.

do_get_icon() → Icon

Gets the icon for drive.

do_get_identifier(kind: str) → str | None

Gets the identifier of the given kind for drive. The only identifier currently available is DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.

Parameters:

kind – the kind of identifier to return

do_get_name() → str

Gets the name of drive.

do_get_sort_key() → str | None

Gets the sort key for drive, if any.

Added in version 2.32.

do_get_start_stop_type() → DriveStartStopType

Gets a hint about how a drive can be started/stopped.

Added in version 2.22.

do_get_symbolic_icon() → Icon

Gets the icon for drive.

Added in version 2.34.

do_get_volumes() → list[Volume]

Get a list of mountable volumes for drive.

The returned list should be freed with free(), after its elements have been unreffed with unref().

do_has_media() → bool

Checks if the drive has media. Note that the OS may not be polling the drive for media changes; see is_media_check_automatic() for more details.

do_has_volumes() → bool

Check if drive has any mountable volumes.

do_is_media_check_automatic() → bool

Checks if drive is capable of automatically detecting media changes.

do_is_media_removable() → bool

Checks if the drive supports removable media.

do_is_removable() → bool

Checks if the Drive and/or its media is considered removable by the user. See is_media_removable().

Added in version 2.50.

do_poll_for_media(cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously polls drive to see if media has been inserted or removed.

When the operation is finished, callback will be called. You can then call poll_for_media_finish() to obtain the result of the operation.

Parameters:

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

do_poll_for_media_finish(result: AsyncResult) → bool

Finishes an operation started with poll_for_media() on a drive.

Parameters:

result – a AsyncResult.

do_start(flags: DriveStartFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously starts a drive.

When the operation is finished, callback will be called. You can then call start_finish() to obtain the result of the operation.

Added in version 2.22.

Parameters:

• flags – flags affecting the start operation.

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

do_start_finish(result: AsyncResult) → bool

Finishes starting a drive.

Added in version 2.22.

Parameters:

result – a AsyncResult.

do_stop(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None

Asynchronously stops a drive.

When the operation is finished, callback will be called. You can then call stop_finish() to obtain the result of the operation.

Added in version 2.22.

Parameters:

• flags – flags affecting the unmount if required for stopping.

• mount_operation – a MountOperation or None to avoid user interaction.

• cancellable – optional Cancellable object, None to ignore.

• callback – a AsyncReadyCallback, or None.

• user_data – user data to pass to callback

do_stop_button() → None

The type of the None singleton.

do_stop_finish(result: AsyncResult) → bool

Finishes stopping a drive.

Added in version 2.22.

Parameters:

result – a AsyncResult.