FileInfo#

class FileInfo(**properties: Any)#

Superclasses: 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 query_info (or its async variant). To obtain a GFileInfo for a file input or output stream, use query_info or 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 set_attributes_from_info or 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 set_size. You may call query_settable_attributes and query_writable_namespaces to discover the settable attributes of a particular file at runtime.

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

FileAttributeMatcher allows for searching through a GFileInfo for attributes.

Constructors#

class FileInfo
classmethod new() → FileInfo#

Creates a new file info structure.

Methods#

class FileInfo
clear_status() → None#

Clears the status information from info.

dup() → FileInfo#

Duplicates a file info structure.

get_access_date_time() → DateTime | None#

Gets the access time of the current info and returns it as a 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 DateTime will additionally have microsecond precision.

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

Added in version 2.70.

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.

Parameters:

attribute – a file attribute key.

get_attribute_boolean(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(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(attribute: str) → tuple[bool, FileAttributeType, Any, FileAttributeStatus]#

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

Parameters:

attribute – a file attribute key

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.

Added in version 2.78.

Parameters:

attribute – a file attribute key.

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.

Parameters:

attribute – a file attribute key.

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.

Parameters:

attribute – a file attribute key.

get_attribute_object(attribute: str) → Object | None#

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

Parameters:

attribute – a file attribute key.

get_attribute_status(attribute: str) → FileAttributeStatus#

Gets the attribute status for an attribute key.

Parameters:

attribute – a file attribute key

get_attribute_string(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(attribute: str) → list[str] | None#

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

Added in version 2.22.

Parameters:

attribute – a file attribute key.

get_attribute_type(attribute: str) → FileAttributeType#

Gets the attribute type for an attribute key.

Parameters:

attribute – a file attribute key.

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.

Parameters:

attribute – a file attribute key.

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.

Parameters:

attribute – a file attribute key.

get_content_type() → 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() → DateTime | None#

Gets the creation time of the current info and returns it as a 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 DateTime will additionally have microsecond precision.

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

Added in version 2.70.

get_deletion_date() → DateTime | None#

Returns the 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.

Added in version 2.36.

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 FileInfo does not contain FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.

get_edit_name() → 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() → str | None#

Gets the entity tag 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() → FileType#

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

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

get_icon() → 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() → bool#

Checks if a file is a backup file.

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

get_is_hidden() → 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.

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() → DateTime | None#

Gets the modification time of the current info and returns it as a 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 DateTime will additionally have microsecond precision.

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

Added in version 2.62.

get_modification_time() → TimeVal#

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.

Deprecated since version 2.62:

Use get_modification_date_time() instead, as

TimeVal is deprecated due to the year 2038 problem.

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 FileInfo does not contain FILE_ATTRIBUTE_STANDARD_NAME.

get_size() → 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 int to gint64 before returning the result.

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

get_sort_order() → 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() → 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.

Added in version 2.34.

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(attribute: str) → bool#

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

Parameters:

attribute – a file attribute key.

has_namespace(name_space: str) → bool#

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

Added in version 2.22.

Parameters:

name_space – a file attribute namespace.

list_attributes(name_space: str | None = 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(attribute: str) → None#

Removes all cases of attribute from info if it exists.

Parameters:

attribute – a file attribute key.

set_access_date_time(atime: 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.

Added in version 2.70.

Parameters:

atime – a DateTime.

set_attribute(attribute: str, type: FileAttributeType, value_p: Any) → None#

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

Parameters:

  • attribute – a file attribute key.

  • type – a FileAttributeType

  • value_p – pointer to the value

set_attribute_boolean(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(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(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.

Added in version 2.78.

Parameters:

  • attribute – a file attribute key.

  • attr_value – a file path.

set_attribute_int32(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(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(mask: FileAttributeMatcher) → None#

Sets mask on info to match specific attribute types.

Parameters:

mask – a FileAttributeMatcher.

set_attribute_object(attribute: str, attr_value: Object) → None#

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

Parameters:

  • attribute – a file attribute key.

  • attr_value – a Object.

set_attribute_status(attribute: str, status: FileAttributeStatus) → bool#

Sets the attribute status for an attribute key. This is only needed by external code that implement 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.

Added in version 2.22.

Parameters:
set_attribute_string(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(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(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(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(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. See [GContentType][gio-GContentType]

set_creation_date_time(creation_time: 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.

Added in version 2.70.

Parameters:

creation_time – a DateTime.

set_display_name(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(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(type: FileType) → None#

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

Parameters:

type – a FileType.

set_icon(icon: Icon) → None#

Sets the icon for a given FileInfo. See FILE_ATTRIBUTE_STANDARD_ICON.

Parameters:

icon – a Icon.

set_is_hidden(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.

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(mtime: 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.

Added in version 2.62.

Parameters:

mtime – a DateTime.

set_modification_time(mtime: TimeVal) → None#

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.

Deprecated since version 2.62:

Use set_modification_date_time() instead, as

TimeVal is deprecated due to the year 2038 problem.

Parameters:

mtime – a TimeVal.

set_name(name: str) → None#

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

Parameters:

name – a string containing a name.

set_size(size: int) → None#

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

Parameters:

size – a gint64 containing the file’s size.

set_sort_order(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(icon: Icon) → None#

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

Added in version 2.34.

Parameters:

icon – a Icon.

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() → None#

Unsets a mask set by set_attribute_mask(), if one is set.

On this page

This Page