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 file-attributes.html 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, None, 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 guint64 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: None) → 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: Sequence[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.