:right-sidebar: True FileInfo =================================================================== .. currentmodule:: gi.repository.Gio .. class:: FileInfo(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Stores information about a file system object referenced by a :obj:`~gi.repository.Gio.File`\. Functionality for manipulating basic metadata for files. ``GFileInfo`` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. See the `file attributes `__ document for more information on how GIO handles file attributes. To obtain a ``GFileInfo`` for a :obj:`~gi.repository.Gio.File`\, use :obj:`~gi.repository.Gio.File.query_info` (or its async variant). To obtain a ``GFileInfo`` for a file input or output stream, use :obj:`~gi.repository.Gio.FileInputStream.query_info` or :obj:`~gi.repository.Gio.FileOutputStream.query_info` (or their async variants). To change the actual attributes of a file, you should then set the attribute in the ``GFileInfo`` and call :obj:`~gi.repository.Gio.File.set_attributes_from_info` or :obj:`~gi.repository.Gio.File.set_attributes_async` on a ``GFile``\. However, not all attributes can be changed in the file. For instance, the actual size of a file cannot be changed via :obj:`~gi.repository.Gio.FileInfo.set_size`\. You may call :obj:`~gi.repository.Gio.File.query_settable_attributes` and :obj:`~gi.repository.Gio.File.query_writable_namespaces` to discover the settable attributes of a particular file at runtime. The direct accessors, such as :obj:`~gi.repository.Gio.FileInfo.get_name`\, are slightly more optimized than the generic attribute accessors, such as :obj:`~gi.repository.Gio.FileInfo.get_attribute_byte_string`\.This optimization will matter only if calling the API in a tight loop. It is an error to call these accessors without specifying their required file attributes when creating the ``GFileInfo``\. Use :obj:`~gi.repository.Gio.FileInfo.has_attribute` or :obj:`~gi.repository.Gio.FileInfo.list_attributes` to check what attributes are specified for a ``GFileInfo``\. :obj:`~gi.repository.Gio.FileAttributeMatcher` allows for searching through a ``GFileInfo`` for attributes. Constructors ------------ .. rst-class:: interim-class .. class:: FileInfo :no-index: .. classmethod:: new() -> ~gi.repository.Gio.FileInfo Creates a new file info structure. Methods ------- .. rst-class:: interim-class .. class:: FileInfo :no-index: .. method:: clear_status() -> None Clears the status information from ``info``\. .. method:: dup() -> ~gi.repository.Gio.FileInfo Duplicates a file info structure. .. method:: get_access_date_time() -> ~gi.repository.GLib.DateTime | None Gets the access time of the current ``info`` and returns it as a :obj:`~gi.repository.GLib.DateTime`\. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS`. If :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS_USEC` is provided, the resulting :obj:`~gi.repository.GLib.DateTime` will additionally have microsecond precision. If nanosecond precision is needed, :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS_NSEC` must be queried separately using :func:`~gi.repository.Gio.FileInfo.get_attribute_uint32`. .. versionadded:: 2.70 .. method:: get_attribute_as_string(attribute: str) -> str | None Gets the value of an attribute, formatted as a string. This escapes things as needed to make the string valid UTF-8. :param attribute: a file attribute key. .. method:: get_attribute_boolean(attribute: str) -> bool Gets the value of a boolean attribute. If the attribute does not contain a boolean value, :const:`False` will be returned. :param attribute: a file attribute key. .. method:: get_attribute_byte_string(attribute: str) -> str | None Gets the value of a byte string attribute. If the attribute does not contain a byte string, :const:`None` will be returned. :param attribute: a file attribute key. .. method:: get_attribute_data(attribute: str) -> ~typing.Tuple[bool, ~gi.repository.Gio.FileAttributeType, ~typing.Any, ~gi.repository.Gio.FileAttributeStatus] Gets the attribute type, value and status for an attribute key. :param attribute: a file attribute key .. method:: get_attribute_file_path(attribute: str) -> str | None Gets the value of a byte string attribute as a file path. If the attribute does not contain a byte string, ``NULL`` will be returned. This function is meant to be used by language bindings that have specific handling for Unix paths. .. versionadded:: 2.78 :param attribute: a file attribute key. .. method:: get_attribute_int32(attribute: str) -> int Gets a signed 32-bit integer contained within the attribute. If the attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned. :param attribute: a file attribute key. .. method:: get_attribute_int64(attribute: str) -> int Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain a signed 64-bit integer, or is invalid, 0 will be returned. :param attribute: a file attribute key. .. method:: get_attribute_object(attribute: str) -> ~gi.repository.GObject.Object | None Gets the value of a :obj:`~gi.repository.GObject.Object` attribute. If the attribute does not contain a :obj:`~gi.repository.GObject.Object`\, :const:`None` will be returned. :param attribute: a file attribute key. .. method:: get_attribute_status(attribute: str) -> ~gi.repository.Gio.FileAttributeStatus Gets the attribute status for an attribute key. :param attribute: a file attribute key .. method:: get_attribute_string(attribute: str) -> str | None Gets the value of a string attribute. If the attribute does not contain a string, :const:`None` will be returned. :param attribute: a file attribute key. .. method:: get_attribute_stringv(attribute: str) -> list[str] | None Gets the value of a stringv attribute. If the attribute does not contain a stringv, :const:`None` will be returned. .. versionadded:: 2.22 :param attribute: a file attribute key. .. method:: get_attribute_type(attribute: str) -> ~gi.repository.Gio.FileAttributeType Gets the attribute type for an attribute key. :param attribute: a file attribute key. .. method:: get_attribute_uint32(attribute: str) -> int Gets an unsigned 32-bit integer contained within the attribute. If the attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned. :param attribute: a file attribute key. .. method:: get_attribute_uint64(attribute: str) -> int Gets a unsigned 64-bit integer contained within the attribute. If the attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned. :param attribute: a file attribute key. .. method:: get_content_type() -> str | None Gets the file's content type. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE`. .. method:: get_creation_date_time() -> ~gi.repository.GLib.DateTime | None Gets the creation time of the current ``info`` and returns it as a :obj:`~gi.repository.GLib.DateTime`\. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED`. If :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED_USEC` is provided, the resulting :obj:`~gi.repository.GLib.DateTime` will additionally have microsecond precision. If nanosecond precision is needed, :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED_NSEC` must be queried separately using :func:`~gi.repository.Gio.FileInfo.get_attribute_uint32`. .. versionadded:: 2.70 .. method:: get_deletion_date() -> ~gi.repository.GLib.DateTime | None Returns the :obj:`~gi.repository.GLib.DateTime` representing the deletion date of the file, as available in :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TRASH_DELETION_DATE`. If the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TRASH_DELETION_DATE` attribute is unset, :const:`None` is returned. .. versionadded:: 2.36 .. method:: get_display_name() -> str Gets a display name for a file. This is guaranteed to always be set. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME`. .. method:: get_edit_name() -> str Gets the edit name for a file. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME`. .. method:: get_etag() -> str | None Gets the `entity tag `__ for a given :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_ETAG_VALUE`. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_ETAG_VALUE`. .. method:: get_file_type() -> ~gi.repository.Gio.FileType Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see :func:`~gi.repository.Gio.FileInfo.get_content_type`. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_TYPE`. .. method:: get_icon() -> ~gi.repository.Gio.Icon | None Gets the icon for a file. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_ICON`. .. method:: get_is_backup() -> bool Checks if a file is a backup file. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_IS_BACKUP`. .. method:: get_is_hidden() -> bool Checks if a file is hidden. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_IS_HIDDEN`. .. method:: get_is_symlink() -> bool Checks if a file is a symlink. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_IS_SYMLINK`. .. method:: get_modification_date_time() -> ~gi.repository.GLib.DateTime | None Gets the modification time of the current ``info`` and returns it as a :obj:`~gi.repository.GLib.DateTime`\. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED`. If :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC` is provided, the resulting :obj:`~gi.repository.GLib.DateTime` will additionally have microsecond precision. If nanosecond precision is needed, :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_NSEC` must be queried separately using :func:`~gi.repository.Gio.FileInfo.get_attribute_uint32`. .. versionadded:: 2.62 .. method:: get_modification_time() -> ~gi.repository.GLib.TimeVal Gets the modification time of the current ``info`` and sets it in ``result``\. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED`. If :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC` is provided it will be used too. .. deprecated:: 2.62 Use :func:`~gi.repository.Gio.FileInfo.get_modification_date_time` instead, as :obj:`~gi.repository.GLib.TimeVal` is deprecated due to the year 2038 problem. .. method:: get_name() -> str Gets the name for a file. This is guaranteed to always be set. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_NAME`. .. method:: get_size() -> int Gets the file's size (in bytes). The size is retrieved through the value of the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SIZE` attribute and is converted from :obj:`int` to :obj:`~gi.repository.gint64` before returning the result. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SIZE`. .. method:: get_sort_order() -> int Gets the value of the sort_order attribute from the :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. .. method:: get_symbolic_icon() -> ~gi.repository.Gio.Icon | None Gets the symbolic icon for a file. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON`. .. versionadded:: 2.34 .. method:: get_symlink_target() -> str | None Gets the symlink target for a given :obj:`~gi.repository.Gio.FileInfo`\. It is an error to call this if the :obj:`~gi.repository.Gio.FileInfo` does not contain :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET`. .. method:: has_attribute(attribute: str) -> bool Checks if a file info structure has an attribute named ``attribute``\. :param attribute: a file attribute key. .. method:: has_namespace(name_space: str) -> bool Checks if a file info structure has an attribute in the specified ``name_space``\. .. versionadded:: 2.22 :param name_space: a file attribute namespace. .. method:: list_attributes(name_space: str | None = None) -> list[str] | None Lists the file info structure's attributes. :param name_space: a file attribute key's namespace, or :const:`None` to list all attributes. .. method:: remove_attribute(attribute: str) -> None Removes all cases of ``attribute`` from ``info`` if it exists. :param attribute: a file attribute key. .. method:: set_access_date_time(atime: ~gi.repository.GLib.DateTime) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS` and :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS_USEC` attributes in the file info to the given date/time value. :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_ACCESS_NSEC` will be cleared. .. versionadded:: 2.70 :param atime: a :obj:`~gi.repository.GLib.DateTime`\. .. method:: set_attribute(attribute: str, type: ~gi.repository.Gio.FileAttributeType, value_p: ~typing.Any) -> None Sets the ``attribute`` to contain the given value, if possible. To unset the attribute, use :const:`~gi.repository.Gio.FileAttributeType.INVALID` for ``type``\. :param attribute: a file attribute key. :param type: a :obj:`~gi.repository.Gio.FileAttributeType` :param value_p: pointer to the value .. method:: set_attribute_boolean(attribute: str, attr_value: bool) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: a boolean value. .. method:: set_attribute_byte_string(attribute: str, attr_value: str) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: a byte string. .. method:: set_attribute_file_path(attribute: str, attr_value: str) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. This function is meant to be used by language bindings that have specific handling for Unix paths. .. versionadded:: 2.78 :param attribute: a file attribute key. :param attr_value: a file path. .. method:: set_attribute_int32(attribute: str, attr_value: int) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: a signed 32-bit integer .. method:: set_attribute_int64(attribute: str, attr_value: int) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: attribute name to set. :param attr_value: int64 value to set attribute to. .. method:: set_attribute_mask(mask: ~gi.repository.Gio.FileAttributeMatcher) -> None Sets ``mask`` on ``info`` to match specific attribute types. :param mask: a :obj:`~gi.repository.Gio.FileAttributeMatcher`\. .. method:: set_attribute_object(attribute: str, attr_value: ~gi.repository.GObject.Object) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: a :obj:`~gi.repository.GObject.Object`\. .. method:: set_attribute_status(attribute: str, status: ~gi.repository.Gio.FileAttributeStatus) -> bool Sets the attribute status for an attribute key. This is only needed by external code that implement :func:`~gi.repository.Gio.File.set_attributes_from_info` or similar functions. The attribute must exist in ``info`` for this to work. Otherwise :const:`False` is returned and ``info`` is unchanged. .. versionadded:: 2.22 :param attribute: a file attribute key :param status: a :obj:`~gi.repository.Gio.FileAttributeStatus` .. method:: set_attribute_string(attribute: str, attr_value: str) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: a UTF-8 string. .. method:: set_attribute_stringv(attribute: str, attr_value: list[str]) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. Sinze: 2.22 :param attribute: a file attribute key :param attr_value: a :const:`None` terminated array of UTF-8 strings. .. method:: set_attribute_uint32(attribute: str, attr_value: int) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: an unsigned 32-bit integer. .. method:: set_attribute_uint64(attribute: str, attr_value: int) -> None Sets the ``attribute`` to contain the given ``attr_value``\, if possible. :param attribute: a file attribute key. :param attr_value: an unsigned 64-bit integer. .. method:: set_content_type(content_type: str) -> None Sets the content type attribute for a given :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE`. :param content_type: a content type. See [GContentType][gio-GContentType] .. method:: set_creation_date_time(creation_time: ~gi.repository.GLib.DateTime) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED` and :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED_USEC` attributes in the file info to the given date/time value. :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_CREATED_NSEC` will be cleared. .. versionadded:: 2.70 :param creation_time: a :obj:`~gi.repository.GLib.DateTime`\. .. method:: set_display_name(display_name: str) -> None Sets the display name for the current :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME`. :param display_name: a string containing a display name. .. method:: set_edit_name(edit_name: str) -> None Sets the edit name for the current file. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME`. :param edit_name: a string containing an edit name. .. method:: set_file_type(type: ~gi.repository.Gio.FileType) -> None Sets the file type in a :obj:`~gi.repository.Gio.FileInfo` to ``type``\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_TYPE`. :param type: a :obj:`~gi.repository.Gio.FileType`\. .. method:: set_icon(icon: ~gi.repository.Gio.Icon) -> None Sets the icon for a given :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_ICON`. :param icon: a :obj:`~gi.repository.Gio.Icon`\. .. method:: set_is_hidden(is_hidden: bool) -> None Sets the "is_hidden" attribute in a :obj:`~gi.repository.Gio.FileInfo` according to ``is_hidden``\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_IS_HIDDEN`. :param is_hidden: a :obj:`~gi.repository.gboolean`\. .. method:: set_is_symlink(is_symlink: bool) -> None Sets the "is_symlink" attribute in a :obj:`~gi.repository.Gio.FileInfo` according to ``is_symlink``\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_IS_SYMLINK`. :param is_symlink: a :obj:`~gi.repository.gboolean`\. .. method:: set_modification_date_time(mtime: ~gi.repository.GLib.DateTime) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED` and :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC` attributes in the file info to the given date/time value. :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_NSEC` will be cleared. .. versionadded:: 2.62 :param mtime: a :obj:`~gi.repository.GLib.DateTime`\. .. method:: set_modification_time(mtime: ~gi.repository.GLib.TimeVal) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED` and :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC` attributes in the file info to the given time value. :const:`~gi.repository.Gio.FILE_ATTRIBUTE_TIME_MODIFIED_NSEC` will be cleared. .. deprecated:: 2.62 Use :func:`~gi.repository.Gio.FileInfo.set_modification_date_time` instead, as :obj:`~gi.repository.GLib.TimeVal` is deprecated due to the year 2038 problem. :param mtime: a :obj:`~gi.repository.GLib.TimeVal`\. .. method:: set_name(name: str) -> None Sets the name attribute for the current :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_NAME`. :param name: a string containing a name. .. method:: set_size(size: int) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SIZE` attribute in the file info to the given size. :param size: a :obj:`~gi.repository.gint64` containing the file's size. .. method:: set_sort_order(sort_order: int) -> None Sets the sort order attribute in the file info structure. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. :param sort_order: a sort order integer. .. method:: set_symbolic_icon(icon: ~gi.repository.Gio.Icon) -> None Sets the symbolic icon for a given :obj:`~gi.repository.Gio.FileInfo`\. See :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON`. .. versionadded:: 2.34 :param icon: a :obj:`~gi.repository.Gio.Icon`\. .. method:: set_symlink_target(symlink_target: str) -> None Sets the :const:`~gi.repository.Gio.FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET` attribute in the file info to the given symlink target. :param symlink_target: a static string containing a path to a symlink target. .. method:: unset_attribute_mask() -> None Unsets a mask set by :func:`~gi.repository.Gio.FileInfo.set_attribute_mask`, if one is set.