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.

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.

eject(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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.

eject_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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.

poll_for_media(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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.

start(flags: DriveStartFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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.

stop(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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

Emitted when the drive’s state has changed.

disconnected() → None

This signal is emitted when the Drive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.

eject_button() → None

Emitted when the physical eject button (if any) of a drive has been pressed.

stop_button() → None

Emitted when the physical stop button (if any) of a drive has been pressed.

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

Signal emitted when the drive is changed.

do_disconnected() → None

The removed signal that is emitted when the Drive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.

do_eject(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → 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

Signal emitted when the physical eject button (if any) of a drive have been pressed.

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[[...], None] | None = None, *user_data: Any) → 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[[...], None] | None = None, *user_data: Any) → 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[[...], None] | None = None, *user_data: Any) → 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[[...], None] | None = None, *user_data: Any) → 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

Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.

do_stop_finish(result: AsyncResult) → bool

Finishes stopping a drive.

Added in version 2.22.

Parameters:

result – a AsyncResult.