:right-sidebar: True Drive =================================================================== .. currentmodule:: gi.repository.Gio .. class:: Drive(*args, **kwargs) :no-contents-entry: ``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 :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.Drive.get_start_stop_type`\. For `porting from GnomeVFS `__ note that there is no equivalent of ``GDrive`` in that API. Methods ------- .. rst-class:: interim-class .. class:: Drive :no-index: .. method:: can_eject() -> bool Checks if a drive can be ejected. .. method:: can_poll_for_media() -> bool Checks if a drive can be polled for media changes. .. method:: can_start() -> bool Checks if a drive can be started. .. versionadded:: 2.22 .. method:: can_start_degraded() -> bool Checks if a drive can be started degraded. .. versionadded:: 2.22 .. method:: can_stop() -> bool Checks if a drive can be stopped. .. versionadded:: 2.22 .. method:: eject(flags: ~gi.repository.Gio.MountUnmountFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously ejects a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.eject_finish` to obtain the result of the operation. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Drive.eject_with_operation` instead. :param flags: flags affecting the unmount if required for eject :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: eject_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a drive. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Drive.eject_with_operation_finish` instead. :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: eject_with_operation(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a drive. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Drive.eject_with_operation_finish` with the ``drive`` and :obj:`~gi.repository.Gio.AsyncResult` data returned in the ``callback``\. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for eject :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data passed to ``callback``\. .. method:: eject_with_operation_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a drive. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: enumerate_identifiers() -> list[str] Gets the kinds of identifiers that ``drive`` has. Use :func:`~gi.repository.Gio.Drive.get_identifier` to obtain the identifiers themselves. .. method:: get_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``drive``\. .. method:: get_identifier(kind: str) -> str | None Gets the identifier of the given kind for ``drive``\. The only identifier currently available is :const:`~gi.repository.Gio.DRIVE_IDENTIFIER_KIND_UNIX_DEVICE`. :param kind: the kind of identifier to return .. method:: get_name() -> str Gets the name of ``drive``\. .. method:: get_sort_key() -> str | None Gets the sort key for ``drive``\, if any. .. versionadded:: 2.32 .. method:: get_start_stop_type() -> ~gi.repository.Gio.DriveStartStopType Gets a hint about how a drive can be started/stopped. .. versionadded:: 2.22 .. method:: get_symbolic_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``drive``\. .. versionadded:: 2.34 .. method:: get_volumes() -> list[~gi.repository.Gio.Volume] Get a list of mountable volumes for ``drive``\. The returned list should be freed with :func:`~gi.repository.GLib.List.free`, after its elements have been unreffed with :func:`~gi.repository.GObject.GObject.Object.unref`. .. method:: has_media() -> bool Checks if the ``drive`` has media. Note that the OS may not be polling the drive for media changes; see :func:`~gi.repository.Gio.Drive.is_media_check_automatic` for more details. .. method:: has_volumes() -> bool Check if ``drive`` has any mountable volumes. .. method:: is_media_check_automatic() -> bool Checks if ``drive`` is capable of automatically detecting media changes. .. method:: is_media_removable() -> bool Checks if the ``drive`` supports removable media. .. method:: is_removable() -> bool Checks if the :obj:`~gi.repository.Gio.Drive` and/or its media is considered removable by the user. See :func:`~gi.repository.Gio.Drive.is_media_removable`. .. versionadded:: 2.50 .. method:: poll_for_media(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.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 :func:`~gi.repository.Gio.Drive.poll_for_media_finish` to obtain the result of the operation. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: poll_for_media_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes an operation started with :func:`~gi.repository.Gio.Drive.poll_for_media` on a drive. :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: start(flags: ~gi.repository.Gio.DriveStartFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously starts a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.start_finish` to obtain the result of the operation. .. versionadded:: 2.22 :param flags: flags affecting the start operation. :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: start_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes starting a drive. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: stop(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously stops a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.stop_finish` to obtain the result of the operation. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for stopping. :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: stop_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes stopping a drive. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. Signals ------- .. rst-class:: interim-class .. class:: Drive.signals :no-index: .. method:: changed() -> None The type of the None singleton. .. method:: disconnected() -> None The type of the None singleton. .. method:: eject_button() -> None The type of the None singleton. .. method:: stop_button() -> None The type of the None singleton. .. versionadded:: 2.22 Virtual Methods --------------- .. rst-class:: interim-class .. class:: Drive :no-index: .. method:: do_can_eject() -> bool Checks if a drive can be ejected. .. method:: do_can_poll_for_media() -> bool Checks if a drive can be polled for media changes. .. method:: do_can_start() -> bool Checks if a drive can be started. .. versionadded:: 2.22 .. method:: do_can_start_degraded() -> bool Checks if a drive can be started degraded. .. versionadded:: 2.22 .. method:: do_can_stop() -> bool Checks if a drive can be stopped. .. versionadded:: 2.22 .. method:: do_changed() -> None The type of the None singleton. .. method:: do_disconnected() -> None The type of the None singleton. .. method:: do_eject(flags: ~gi.repository.Gio.MountUnmountFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously ejects a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.eject_finish` to obtain the result of the operation. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Drive.eject_with_operation` instead. :param flags: flags affecting the unmount if required for eject :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: do_eject_button() -> None The type of the None singleton. .. method:: do_eject_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a drive. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Drive.eject_with_operation_finish` instead. :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: do_eject_with_operation(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a drive. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Drive.eject_with_operation_finish` with the ``drive`` and :obj:`~gi.repository.Gio.AsyncResult` data returned in the ``callback``\. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for eject :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data passed to ``callback``\. .. method:: do_eject_with_operation_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a drive. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: do_enumerate_identifiers() -> list[str] Gets the kinds of identifiers that ``drive`` has. Use :func:`~gi.repository.Gio.Drive.get_identifier` to obtain the identifiers themselves. .. method:: do_get_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``drive``\. .. method:: do_get_identifier(kind: str) -> str | None Gets the identifier of the given kind for ``drive``\. The only identifier currently available is :const:`~gi.repository.Gio.DRIVE_IDENTIFIER_KIND_UNIX_DEVICE`. :param kind: the kind of identifier to return .. method:: do_get_name() -> str Gets the name of ``drive``\. .. method:: do_get_sort_key() -> str | None Gets the sort key for ``drive``\, if any. .. versionadded:: 2.32 .. method:: do_get_start_stop_type() -> ~gi.repository.Gio.DriveStartStopType Gets a hint about how a drive can be started/stopped. .. versionadded:: 2.22 .. method:: do_get_symbolic_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``drive``\. .. versionadded:: 2.34 .. method:: do_get_volumes() -> list[~gi.repository.Gio.Volume] Get a list of mountable volumes for ``drive``\. The returned list should be freed with :func:`~gi.repository.GLib.List.free`, after its elements have been unreffed with :func:`~gi.repository.GObject.GObject.Object.unref`. .. method:: do_has_media() -> bool Checks if the ``drive`` has media. Note that the OS may not be polling the drive for media changes; see :func:`~gi.repository.Gio.Drive.is_media_check_automatic` for more details. .. method:: do_has_volumes() -> bool Check if ``drive`` has any mountable volumes. .. method:: do_is_media_check_automatic() -> bool Checks if ``drive`` is capable of automatically detecting media changes. .. method:: do_is_media_removable() -> bool Checks if the ``drive`` supports removable media. .. method:: do_is_removable() -> bool Checks if the :obj:`~gi.repository.Gio.Drive` and/or its media is considered removable by the user. See :func:`~gi.repository.Gio.Drive.is_media_removable`. .. versionadded:: 2.50 .. method:: do_poll_for_media(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.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 :func:`~gi.repository.Gio.Drive.poll_for_media_finish` to obtain the result of the operation. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: do_poll_for_media_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes an operation started with :func:`~gi.repository.Gio.Drive.poll_for_media` on a drive. :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: do_start(flags: ~gi.repository.Gio.DriveStartFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously starts a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.start_finish` to obtain the result of the operation. .. versionadded:: 2.22 :param flags: flags affecting the start operation. :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: do_start_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes starting a drive. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: do_stop(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously stops a drive. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.Drive.stop_finish` to obtain the result of the operation. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for stopping. :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None`. :param user_data: user data to pass to ``callback`` .. method:: do_stop_button() -> None The type of the None singleton. .. method:: do_stop_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes stopping a drive. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult`\.