Skip to content

Gio.FileInfo

class — extends GObject.Object

Stores information about a file system object referenced by a 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 File, use File.query_info (or its async variant). To obtain a GFileInfo for a file input or output stream, use FileInputStream.query_info or 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 File.set_attributes_from_info or 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 FileInfo.set_size. You may call File.query_settable_attributes and File.query_writable_namespaces to discover the settable attributes of a particular file at runtime.

The direct accessors, such as FileInfo.get_name, are slightly more optimized than the generic attribute accessors, such as 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 FileInfo.has_attribute or FileInfo.list_attributes to check what attributes are specified for a GFileInfo.

FileAttributeMatcher allows for searching through a GFileInfo for attributes.

Constructors

new

@classmethod
def new(cls) -> FileInfo

Creates a new file info structure.

Methods

clear_status

def clear_status(self) -> None

Clears the status information from info.

copy_into

def copy_into(self, dest_info: FileInfo) -> None

First clears all of the GFileAttribute of dest_info, and then copies all of the file attributes from src_info to dest_info.

Parameters:

  • dest_info — destination to copy attributes to.

dup

def dup(self) -> FileInfo

Duplicates a file info structure.

get_access_date_time

def get_access_date_time(self) -> GLib.DateTime | None

Gets the access time of the current info and returns it as a GLib.DateTime.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_TIME_ACCESS. If FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting GLib.DateTime will additionally have microsecond precision.

If nanosecond precision is needed, FILE_ATTRIBUTE_TIME_ACCESS_NSEC must be queried separately using FileInfo.get_attribute_uint32.

get_attribute_as_string

def get_attribute_as_string(self, attribute: str) -> str | None

Gets the value of an attribute, formatted as a human readable string.

This escapes things as needed to make the string valid UTF-8 and readable by humans. It’s not meant to be a machine readable or reversible escaping format.

To format file name attributes of type FileAttributeType.BYTE_STRING for output as UTF-8, use GLib.filename_to_utf8 instead: 

const char *trash_orig_path_byte_string;
g_autofree char *trash_orig_path_utf8 = NULL;

trash_orig_path_byte_string = g_file_info_get_attribute_byte_string (info, G_FILE_ATTRIBUTE_TRASH_ORIG_PATH);
trash_orig_path_utf8 = g_filename_to_utf8 (trash_orig_path_byte_string, -1, NULL, NULL, NULL);
if (trash_orig_path_utf8 != NULL)
  g_message ("Some larger UTF-8 string with filename embedded as %s", trash_orig_path_utf8);

Parameters:

  • attribute — a file attribute key.

get_attribute_boolean

def get_attribute_boolean(self, attribute: str) -> bool

Gets the value of a boolean attribute. If the attribute does not contain a boolean value, False will be returned.

Parameters:

  • attribute — a file attribute key.

get_attribute_byte_string

def get_attribute_byte_string(self, attribute: str) -> str | None

Gets the value of a byte string attribute. If the attribute does not contain a byte string, None will be returned.

Parameters:

  • attribute — a file attribute key.

get_attribute_data

def get_attribute_data(self, attribute: str) -> tuple[bool, FileAttributeType | int, int, FileAttributeStatus | int]

Gets the attribute type, value and status for an attribute key.

Parameters:

  • attribute — a file attribute key

get_attribute_file_path

def get_attribute_file_path(self, 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.

Parameters:

  • attribute — a file attribute key.

get_attribute_int32

def get_attribute_int32(self, 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.

Parameters:

  • attribute — a file attribute key.

get_attribute_int64

def get_attribute_int64(self, 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.

Parameters:

  • attribute — a file attribute key.

get_attribute_object

def get_attribute_object(self, attribute: str) -> GObject.Object | None

Gets the value of a GObject.Object attribute. If the attribute does not contain a GObject.Object, None will be returned.

Parameters:

  • attribute — a file attribute key.

get_attribute_status

def get_attribute_status(self, attribute: str) -> FileAttributeStatus

Gets the attribute status for an attribute key.

Parameters:

  • attribute — a file attribute key

get_attribute_string

def get_attribute_string(self, attribute: str) -> str | None

Gets the value of a string attribute. If the attribute does not contain a string, None will be returned.

Parameters:

  • attribute — a file attribute key.

get_attribute_stringv

def get_attribute_stringv(self, attribute: str) -> list[str] | None

Gets the value of a stringv attribute. If the attribute does not contain a stringv, None will be returned.

Parameters:

  • attribute — a file attribute key.

get_attribute_type

def get_attribute_type(self, attribute: str) -> FileAttributeType

Gets the attribute type for an attribute key.

Parameters:

  • attribute — a file attribute key.

get_attribute_uint32

def get_attribute_uint32(self, 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.

Parameters:

  • attribute — a file attribute key.

get_attribute_uint64

def get_attribute_uint64(self, 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.

Parameters:

  • attribute — a file attribute key.

get_content_type

def get_content_type(self) -> str | None

Gets the file's content type.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.

get_creation_date_time

def get_creation_date_time(self) -> GLib.DateTime | None

Gets the creation time of the current info and returns it as a GLib.DateTime.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_TIME_CREATED. If FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting GLib.DateTime will additionally have microsecond precision.

If nanosecond precision is needed, FILE_ATTRIBUTE_TIME_CREATED_NSEC must be queried separately using FileInfo.get_attribute_uint32.

get_deletion_date

def get_deletion_date(self) -> GLib.DateTime | None

Returns the GLib.DateTime representing the deletion date of the file, as available in FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, None is returned.

get_display_name

def get_display_name(self) -> str

Gets a display name for a file. This is guaranteed to always be set.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.

get_edit_name

def get_edit_name(self) -> str

Gets the edit name for a file.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_EDIT_NAME.

get_etag

def get_etag(self) -> str | None

Gets the [entity tag][ifaceGio.File#entity-tags] for a given FileInfo. See FILE_ATTRIBUTE_ETAG_VALUE.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_ETAG_VALUE.

get_file_type

def get_file_type(self) -> FileType

Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see FileInfo.get_content_type.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_TYPE.

get_icon

def get_icon(self) -> Icon | None

Gets the icon for a file.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_ICON.

get_is_backup

def get_is_backup(self) -> bool

Checks if a file is a backup file.

The exact semantics of what constitutes a backup file are backend-specific. For local files, a file is considered a backup if its name ends with ~ and it is a regular file. This follows the POSIX convention used by text editors such as Emacs.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_IS_BACKUP.

get_is_hidden

def get_is_hidden(self) -> bool

Checks if a file is hidden.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.

def get_is_symlink(self) -> bool

Checks if a file is a symlink.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.

get_modification_date_time

def get_modification_date_time(self) -> GLib.DateTime | None

Gets the modification time of the current info and returns it as a GLib.DateTime.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_TIME_MODIFIED. If FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting GLib.DateTime will additionally have microsecond precision.

If nanosecond precision is needed, FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must be queried separately using FileInfo.get_attribute_uint32.

get_modification_time

def get_modification_time(self) -> GLib.TimeVal

:::warning Deprecated since 2.62 This API is deprecated. :::

Gets the modification time of the current info and sets it in result.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_TIME_MODIFIED. If FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided it will be used too.

get_name

def get_name(self) -> str

Gets the name for a file. This is guaranteed to always be set.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_NAME.

get_size

def get_size(self) -> int

Gets the file's size (in bytes). The size is retrieved through the value of the FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted from #guint64 to #goffset before returning the result.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_SIZE.

get_sort_order

def get_sort_order(self) -> int

Gets the value of the sort_order attribute from the FileInfo. See FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

get_symbolic_icon

def get_symbolic_icon(self) -> Icon | None

Gets the symbolic icon for a file.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.

def get_symlink_target(self) -> str | None

Gets the symlink target for a given FileInfo.

It is an error to call this if the FileInfo does not contain FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET.

has_attribute

def has_attribute(self, attribute: str) -> bool

Checks if a file info structure has an attribute named attribute.

Parameters:

  • attribute — a file attribute key.

has_namespace

def has_namespace(self, name_space: str) -> bool

Checks if a file info structure has an attribute in the specified name_space.

Parameters:

  • name_space — a file attribute namespace.

list_attributes

def list_attributes(self, name_space: str | None = ...) -> list[str] | None

Lists the file info structure's attributes.

Parameters:

  • name_space — a file attribute key's namespace, or None to list all attributes.

remove_attribute

def remove_attribute(self, attribute: str) -> None

Removes all cases of attribute from info if it exists.

Parameters:

  • attribute — a file attribute key.

set_access_date_time

def set_access_date_time(self, atime: GLib.DateTime) -> None

Sets the FILE_ATTRIBUTE_TIME_ACCESS and FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the given date/time value.

FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared.

Parameters:

set_attribute

def set_attribute(self, attribute: str, type: FileAttributeType | int, value_p: int) -> None

Sets the attribute to contain the given value, if possible. To unset the attribute, use FileAttributeType.INVALID for type.

Parameters:

  • attribute — a file attribute key.
  • type — a FileAttributeType
  • value_p — pointer to the value

set_attribute_boolean

def set_attribute_boolean(self, attribute: str, attr_value: bool) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a boolean value.

set_attribute_byte_string

def set_attribute_byte_string(self, attribute: str, attr_value: str) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a byte string.

set_attribute_file_path

def set_attribute_file_path(self, attribute: str, attr_value: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> 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.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a file path.

set_attribute_int32

def set_attribute_int32(self, attribute: str, attr_value: int) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a signed 32-bit integer

set_attribute_int64

def set_attribute_int64(self, attribute: str, attr_value: int) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — attribute name to set.
  • attr_value — int64 value to set attribute to.

set_attribute_mask

def set_attribute_mask(self, mask: FileAttributeMatcher) -> None

Sets mask on info to match specific attribute types.

Parameters:

set_attribute_object

def set_attribute_object(self, attribute: str, attr_value: GObject.Object) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a GObject.Object.

set_attribute_status

def set_attribute_status(self, attribute: str, status: FileAttributeStatus | int) -> bool

Sets the attribute status for an attribute key. This is only needed by external code that implement File.set_attributes_from_info or similar functions.

The attribute must exist in info for this to work. Otherwise False is returned and info is unchanged.

Parameters:

set_attribute_string

def set_attribute_string(self, attribute: str, attr_value: str) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — a UTF-8 string.

set_attribute_stringv

def set_attribute_stringv(self, attribute: str, attr_value: list[str]) -> None

Sets the attribute to contain the given attr_value, if possible.

Sinze: 2.22

Parameters:

  • attribute — a file attribute key
  • attr_value — a None terminated array of UTF-8 strings.

set_attribute_uint32

def set_attribute_uint32(self, attribute: str, attr_value: int) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — an unsigned 32-bit integer.

set_attribute_uint64

def set_attribute_uint64(self, attribute: str, attr_value: int) -> None

Sets the attribute to contain the given attr_value, if possible.

Parameters:

  • attribute — a file attribute key.
  • attr_value — an unsigned 64-bit integer.

set_content_type

def set_content_type(self, content_type: str) -> None

Sets the content type attribute for a given FileInfo. See FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.

Parameters:

  • content_type — a content type.

set_creation_date_time

def set_creation_date_time(self, creation_time: GLib.DateTime) -> None

Sets the FILE_ATTRIBUTE_TIME_CREATED and FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the given date/time value.

FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared.

Parameters:

set_display_name

def set_display_name(self, display_name: str) -> None

Sets the display name for the current FileInfo. See FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.

Parameters:

  • display_name — a string containing a display name.

set_edit_name

def set_edit_name(self, edit_name: str) -> None

Sets the edit name for the current file. See FILE_ATTRIBUTE_STANDARD_EDIT_NAME.

Parameters:

  • edit_name — a string containing an edit name.

set_file_type

def set_file_type(self, type: FileType | int) -> None

Sets the file type in a FileInfo to type. See FILE_ATTRIBUTE_STANDARD_TYPE.

Parameters:

set_icon

def set_icon(self, icon: Icon) -> None

Sets the icon for a given FileInfo. See FILE_ATTRIBUTE_STANDARD_ICON.

Parameters:

set_is_hidden

def set_is_hidden(self, is_hidden: bool) -> None

Sets the "is_hidden" attribute in a FileInfo according to is_hidden. See FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.

Parameters:

  • is_hidden — a #gboolean.
def set_is_symlink(self, is_symlink: bool) -> None

Sets the "is_symlink" attribute in a FileInfo according to is_symlink. See FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.

Parameters:

  • is_symlink — a #gboolean.

set_modification_date_time

def set_modification_date_time(self, mtime: GLib.DateTime) -> None

Sets the FILE_ATTRIBUTE_TIME_MODIFIED and FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given date/time value.

FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.

Parameters:

set_modification_time

def set_modification_time(self, mtime: GLib.TimeVal) -> None

:::warning Deprecated since 2.62 This API is deprecated. :::

Sets the FILE_ATTRIBUTE_TIME_MODIFIED and FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given time value.

FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.

Parameters:

set_name

def set_name(self, name: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> None

Sets the name attribute for the current FileInfo. See FILE_ATTRIBUTE_STANDARD_NAME.

Parameters:

  • name — a string containing a name.

set_size

def set_size(self, size: int) -> None

Sets the FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size.

Parameters:

  • size — a #goffset containing the file's size.

set_sort_order

def set_sort_order(self, sort_order: int) -> None

Sets the sort order attribute in the file info structure. See FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

Parameters:

  • sort_order — a sort order integer.

set_symbolic_icon

def set_symbolic_icon(self, icon: Icon) -> None

Sets the symbolic icon for a given FileInfo. See FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.

Parameters:

def set_symlink_target(self, symlink_target: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> None

Sets the FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target.

Parameters:

  • symlink_target — a static string containing a path to a symlink target.

unset_attribute_mask

def unset_attribute_mask(self) -> None

Unsets a mask set by FileInfo.set_attribute_mask, if one is set.