From 784b229c9f54e5197adbd566cd42009e4bcfd055 Mon Sep 17 00:00:00 2001 From: Gian Mario Tagliaretti Date: Sat, 18 Apr 2009 13:32:03 +0200 Subject: Commit some more work on gio.File Docs Added some more methods to gio.File and gio file constants --- docs/reference/pygio-constants.xml | 542 +++++++++++- docs/reference/pygio-file.xml | 1652 +++++++++++++++++++++++++++++++++++- 2 files changed, 2167 insertions(+), 27 deletions(-) diff --git a/docs/reference/pygio-constants.xml b/docs/reference/pygio-constants.xml index 6bddc93..cc71fe3 100644 --- a/docs/reference/pygio-constants.xml +++ b/docs/reference/pygio-constants.xml @@ -15,12 +15,14 @@ + + @@ -301,6 +303,489 @@ + + Gio File Attribute Constants + + + The file attributes. + + + + + gio.FILE_ATTRIBUTE_STANDARD_TYPE + + + "standard::type" A key in the "standard" namespace for storing file types. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. The value for this key should contain a + + + + + + gio.FILE_ATTRIBUTE_STANDARD_IS_HIDDEN + + + "standard::is-hidden" A key in the "standard" namespace for checking if a file is hidden. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_STANDARD_IS_BACKUP + + + "standard::is-backup" A key in the "standard" namespace for checking if a file is a backup file. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_STANDARD_IS_SYMLINK + + + "standard::is-symlink" A key in the "standard" namespace for checking if the file is a symlink. + Typically the actual type is something else, if we followed the symlink to get the type. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL + + + "standard::is-virtual" A key in the "standard" namespace for checking if a file is virtual. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_STANDARD_NAME + + + "standard::name" A key in the "standard" namespace for getting the name of the file. + The name is the on-disk filename which may not be in any known encoding, + and can thus not be generally displayed as is. Use + gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user + interface. Corresponding GFileAttributeType is gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME + + + "standard::display-name" A key in the "standard" namespace for getting the display + name of the file. A display name is guaranteed to be in UTF8 and can thus be displayed + in the UI. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME + + + "standard::edit-name" A key in the "standard" namespace for edit name of the file. + An edit name is similar to the display name, but it is meant to be used when you want + to rename the file in the UI. The display name might contain information you don't + want in the new filename (such as "(invalid unicode)" if the filename was in an + invalid encoding). Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_COPY_NAME + + + "standard::copy-name" A key in the "standard" namespace for getting the copy + name of the file. The copy name is an optional version of the name. If available + it's always in UTF8, and corresponds directly to the original filename (only transcoded + to UTF8). This is useful if you want to copy the file to another filesystem that might + have a different encoding. If the filename is not a valid string in the encoding selected + for the filesystem it is in then the copy name will not be set. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_ICON + + + "standard::icon" A key in the "standard" namespace for getting the icon for the file. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a + gio.Icon. + + + + + gio.FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE + + + "standard::content-type" A key in the "standard" namespace for getting the content type of the file. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. The value for this key should contain a valid content type. + + + + + gio.FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE + + + "standard::fast-content-type" A key in the "standard" namespace for getting the fast + content type. The fast content type isn't as reliable as the regular one, as it + only uses the filename to guess it, but it is faster to calculate than the regular + content type. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_SIZE + + + "standard::size" A key in the "standard" namespace for getting the file's size (in bytes). Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT64. + + + + + gio.FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET + + + "standard::symlink-target" A key in the "standard" namespace for getting the target URI + for the file, in the case of gio.FILE_TYPE_SHORTCUT or gio.FILE_TYPE_MOUNTABLE files. Corresponding + + is G_FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER + + + "standard::sort-order" A key in the "standard" namespace for setting the sort order of a file. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_INT32. An example use would be in file managers, which would use this + key to set the order files are displayed. Files with smaller sort order should be sorted first, + and files without sort order as if sort order was zero. + + + + + gio.FILE_ATTRIBUTE_ETAG_VALUE + + + "etag::value" A key in the "etag" namespace for getting the value of the file's entity tag. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_ID_FILE + + + "id::file" A key in the "id" namespace for getting a file identifier. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during listing files, + to avoid recursive directory scanning. + + + + + gio.FILE_ATTRIBUTE_ID_FILESYSTEM + + + "id::filesystem" A key in the "id" namespace for getting the file system identifier. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during drag and + drop to see if the source and target are on the same filesystem (default to move) or not (default to copy). + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_READ + + + "access::can-read" A key in the "access" namespace for getting read privileges. Corresponding + + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to read the file. + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_WRITE + + + "access::can-write" A key in the "access" namespace for getting write privileges.Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to write to the file. + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE + + + "access::can-execute" A key in the "access" namespace for getting execution privileges. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to execute the file. + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_DELETE + + + "access::can-delete" A key in the "access" namespace for checking deletion privileges. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to delete the file. + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_TRASH + + + "access::can-trash" A key in the "access" namespace for checking trashing privileges. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to move the file to the trash. + + + + + gio.FILE_ATTRIBUTE_ACCESS_CAN_RENAME + + + "access::can-rename" A key in the "access" namespace for checking renaming privileges. Corresponding + + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be True + if the user is able to rename the file. + + + + + gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT + + + "mountable::can-mount" A key in the "mountable" namespace for checking if + a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT + + + "mountable::can-unmount" A key in the "mountable" namespace for checking if a file + (of type G_FILE_TYPE_MOUNTABLE) is unmountable. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT + + + "mountable::can-eject" A key in the "mountable" namespace for checking if a file + (of type G_FILE_TYPE_MOUNTABLE) can be ejected. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + + + + + gio.FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE + + + "mountable::unix-device" A key in the "mountable" namespace for getting the unix device. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI + + + "mountable::hal-udi" A key in the "mountable" namespace for getting the + HAL UDI for the mountable file. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_STRING. + + + + + gio.FILE_ATTRIBUTE_TIME_MODIFIED + + + "time::modified" A key in the "time" namespace for getting the time the file was last modified. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was modified. + + + + + gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC + + + "time::modified-usec" A key in the "time" namespace for getting the miliseconds + of the time the file was last modified. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding + + is G_FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_TIME_ACCESS + + + "time::access" A key in the "time" namespace for getting the time the file was last accessed. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last accessed. + + + + + gio.FILE_ATTRIBUTE_TIME_ACCESS_USEC + + + "time::access-usec" A key in the "time" namespace for getting the microseconds of + the time the file was last accessed. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_TIME_CHANGED + + + "time::changed" A key in the "time" namespace for getting the time the + file was last changed. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last changed. + This corresponds to the traditional UNIX ctime. + + + + + gio.FILE_ATTRIBUTE_TIME_CHANGED_USEC + + + "time::changed-usec" A key in the "time" namespace for getting the microseconds + of the time the file was last changed. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_TIME_CREATED + + + "time::created" A key in the "time" namespace for getting the time the file was created. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was created. + This corresponds to the NTFS ctime. + + + + + gio.FILE_ATTRIBUTE_TIME_CREATED_USEC + + + "time::created-usec" A key in the "time" namespace for getting the microseconds of the time the + file was created. This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_UNIX_DEVICE + + + "unix::device" A key in the "unix" namespace for getting the device id of the device the file + is located on (see stat() documentation). This attribute is only available + for UNIX file systems. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_UNIX_INODE + + + "unix::inode" A key in the "unix" namespace for getting the inode of the file. This attribute is only + available for UNIX file systems. Corresponding + + is G_FILE_ATTRIBUTE_TYPE_UINT64. + + + + + gio.FILE_ATTRIBUTE_UNIX_MODE + + + "unix::mode" A key in the "unix" namespace for getting the mode of the file (e.g. + whether the file is a regular file, symlink, etc). See lstat() documentation. + This attribute is only available for UNIX file systems. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_UNIX_NLINK + + + "unix::nlink" A key in the "unix" namespace for getting the number of hard links + for a file. See lstat() documentation. This attribute is only available for UNIX + file systems. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + gio.FILE_ATTRIBUTE_UNIX_UID + + + "unix::uid" A key in the "unix" namespace for getting the user ID for the file. This attribute + is only available for UNIX file systems. Corresponding + + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + + + + + + Gio File Attribute Type Constants @@ -485,7 +970,7 @@ - Gio File Copy Monitor Constants + Gio File Monitor Flags Constants Flags used to set what a @@ -510,7 +995,7 @@ - Gio File Create Flags Constants + Gio File Query Info Flags Constants Flags used when querying a @@ -533,6 +1018,59 @@ + + Gio File Type Constants + + + Indicates the file's on-disk type. + + + + + gio.FILE_TYPE_DIRECTORY + + File handle represents a directory. + + + + gio.FILE_TYPE_MOUNTABLE + + File is a mountable location. + + + + gio.FILE_TYPE_REGULAR + + File handle represents a regular file. + + + + gio.FILE_TYPE_SHORTCUT + + File is a shortcut (Windows systems). + + + + gio.FILE_TYPE_SPECIAL + + File is a "special" file, such as a socket, fifo, block device, or character device. + + + + gio.FILE_TYPE_SYMBOLIC_LINK + + File handle represents a symbolic link (Unix systems). + + + + gio.FILE_TYPE_UNKNOWN + + File's type is unknown. + + + + + Gio Mount Mount Flags Constants diff --git a/docs/reference/pygio-file.xml b/docs/reference/pygio-file.xml index 148aff7..9c58199 100644 --- a/docs/reference/pygio-file.xml +++ b/docs/reference/pygio-file.xml @@ -5,7 +5,7 @@ gio.File - Information about an installed application and methods to launch it (with file arguments). + File and Directory Handling. @@ -51,11 +51,11 @@ copy_async destination callback + progress_callbackNone flagsgio.FILE_CREATE_NONE io_priorityglib.PRIORITY_DEFAULT - user_dataNone cancellableNone - progress_callbackNone + user_dataNone progress_callback_dataNone @@ -148,11 +148,11 @@ get_child - + name get_child_for_display_name - + display_name get_parent @@ -206,11 +206,11 @@ make_directory - cancellable + cancellableNone make_directory_with_parents - cancellable + cancellableNone make_symbolic_link @@ -219,18 +219,18 @@ monitor - flags - cancellable + flagsgio.FILE_MONITOR_NONE + cancellableNone monitor_directory flags - cancellable + cancellableNone monitor_file flags - cancellable + cancellableNone mount_enclosing_volume @@ -720,7 +720,7 @@ - gio.Volume.append_to_finish + gio.File.append_to_finish append_to_finish @@ -853,11 +853,11 @@ append_to_async destination callback + progress_callbackNone flagsgio.FILE_CREATE_NONE io_priorityglib.PRIORITY_DEFAULT - user_dataNone cancellableNone - progress_callbackNone + user_dataNone progress_callback_dataNone @@ -872,6 +872,11 @@ a GAsyncReadyCallback to call when the request is satisfied. + + progress_callback : + function to callback with progress information. + + flags : a set of @@ -885,11 +890,6 @@ of the request. - - user_data : - the data to pass to callback function. - - cancellable : optional @@ -897,8 +897,8 @@ object, None to ignore. - progress_callback : - function to callback with progress information. + user_data : + the data to pass to callback function. @@ -976,7 +976,7 @@ - gio.Volume.copy_finish + gio.File.copy_finish copy_finish @@ -1119,7 +1119,7 @@ - gio.Volume.create_finish + gio.File.create_finish create_finish @@ -1149,7 +1149,7 @@ - gio.Volume.delete + gio.File.delete delete @@ -1183,7 +1183,7 @@ - gio.Volume.dup + gio.File.dup dup @@ -1211,5 +1211,1607 @@ This call does no blocking i/o. + + + gio.File.eject_mountable + + + eject_mountable + callback + flagsgio.FILE_CREATE_NONE + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + a set of + . + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The eject_mountable() method starts an asynchronous eject on a + mountable. When this operation has completed, callback will be called with + user_user data, and the operation can be finalized with + gio.File.eject_mountable_finish(). + + + If cancellable is not None, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.eject_mountable_finish + + + eject_mountable_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True if the file was ejected successfully, + False on error. + + + + + + The create_finish() method finishes an asynchronous + copy operation started with + gio.File.create_async(). + + + + + gio.File.enumerate_children + + + enumerate_children + attributes + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + + + attributes : + an attribute query string. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a + gio.FileEnumerator + or None on error. + + + + + + The enumerate_children() method gets the requested information + about the files in a directory. The result is a GFileEnumerator object that will give out + gio.FileInfo objects + for all the files in the directory. + + + The attribute value is a string that specifies the file attributes that should be gathered. + It is not an error if it's not possible to read a particular requested attribute from a file - + it just won't be set. attribute should be a comma-separated list of attribute or attribute + wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all + attributes in the standard namespace. An example attribute query be "standard::*,owner::user". + The standard attributes are available as defines, like gio.FILE_ATTRIBUTE_STANDARD_NAME. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. If the file + is not a directory, the gio.FILE_ERROR_NOTDIR error will be returned. + Other errors are possible too. + + + + + gio.File.enumerate_children_async + + + enumerate_children_async + attributes + callback + flagsgio.FILE_QUERY_INFO_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + attributes : + an attribute query string. + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + a set of + . + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The enumerate_children_async() method asynchronously gets the + requested information about the files in a directory. The result is a + gio.FileEnumerator + object that will give out gio.FileInfo + objects for all the files in the directory. + + + For more details, see + enumerate_children() + which is the synchronous version of this call. + + + + + gio.File.eject_mountable_finish + + + enumerate_children_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a gio.FileEnumerator + or None if an error occurred. + + + + + + The enumerate_children_finish() method finishes an asynchronous + copy operation started with + gio.File.enumerate_children_async(). + + + + + gio.File.equal + + + equal + file2 + + + + + file2 : + a gio.File. + + + + Returns : + True if file1 and file2 are equal. + False if either is not a + gio.File. + + + + + + The equal() method checks equality of two given + gio.Files. + Note that two gio.Files + that differ can still refer to the same file on the filesystem due to various + forms of filename aliasing. + + + This call does no blocking i/o. + + + + + gio.File.find_enclosing_mount + + + enumerate_children + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a + gio.Mount + or None on error. + + + + + + The find_enclosing_mount() method gets a + gio.Mount for the + gio.File. + + + If the interface for file does not have a mount (e.g. possibly a remote share), + error will be set to gio.ERROR_NOT_FOUND and None will be returned. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.find_enclosing_mount_async + + + find_enclosing_mount_async + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The find_enclosing_mount_async() method asynchronously + gets the mount for the file. + + + For more details, see + gio.File.find_enclosing_mount() + which is the synchronous version of this call. + + + + + gio.File.find_enclosing_mount_finish + + + find_enclosing_mount_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a gio.Mount + or None if an error occurred. + + + + + + The find_enclosing_mount_finish() method finishes an asynchronous + find mount started with + gio.File.find_enclosing_mount_async(). + + + + + gio.File.get_basename + + + get_basename + + + + + + Returns : + string containing the + gio.File's + base name, or None if given + gio.File is invalid. + + + + + + The get_basename() method gets the base name + (the last component of the path) for a given + gio.File. + + + If called for the top level of a system (such as the filesystem root or + a uri like sftp://host/) it will return a single directory separator + (and on Windows, possibly a drive letter). + + + The base name is a byte string (*not* UTF-8). It has no defined encoding + or rules other than it may not contain zero bytes. If you want to use filenames + in a user interface you should use the display name that you can get by requesting + the gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with + gio.File.query_info(). + + + This call does no blocking i/o. + + + + + gio.File.get_child + + + get_child + name + + + + + name : + string containing the child's basename. + + + + Returns : + a + gio.File + to a child specified by name. + + + + + + The get_child() method gets a child of file + with basename equal to name. + + + Note that the file with that specific name might not exist, but you can + still have a gio.File + that points to it. You can use this for instance to create that file. + + + This call does no blocking i/o. + + + + + gio.File.get_child_for_display_name + + + get_child_for_display_name + display_name + + + + + display_name : + string to a possible child. + + + + Returns : + a + gio.File + to the specified child or None + if the display name couldn't be converted. + + + + + + The get_child_for_display_name() method gets the + child of file for a given display_name (i.e. a UTF8 version of the name). + If this function fails, it returns NULL and error will be set. This is very + useful when constructing a GFile for a new file and the user entered the filename + in the user interface, for instance when you select a directory and type a filename + in the file selector. + + + This call does no blocking i/o. + + + + + gio.File.get_parent + + + get_parent + + + + + + Returns : + a + gio.File + structure to the parent of the given + gio.File or + None if there is no parent. + + + + + + The get_parent() method gets the parent directory for the file. + If the file represents the root directory of the file system, then None + will be returned. + + + This call does no blocking i/o. + + + + + gio.File.get_parse_name + + + get_parse_name + + + + + + Returns : + a string containing the + gio.File's parse name. + + + + + + The get_parse_name() method gets the parse name + of the file. A parse name is a UTF-8 string that describes the file such + that one can get the gio.File + back using + gio.file_parse_name(). + + + This is generally used to show the gio.File + as a nice full-pathname kind of string in a user interface, like in a location entry. + + + For local files with names that can safely be converted to UTF8 the pathname is used, + otherwise the IRI is used (a form of URI that allows UTF8 characters unescaped). + + + This call does no blocking i/o. + + + + + gio.File.get_path + + + get_path + + + + + + Returns : + a string containing the + gio.File's path, + or None if no such path exists. + + + + + + The get_path() method gets the local pathname for + gio.File, if one exists. + + + This call does no blocking i/o. + + + + + gio.File.get_relative_path + + + get_relative_path + descendant + + + + + descendant : + input gio.File. + + + + Returns : + string with the relative path from descendant to parent, + or None if descendant doesn't have parent as prefix. + + + + + + The get_relative_path() method gets the path for + descendant relative to parent. + + + This call does no blocking i/o. + + + + + gio.File.get_uri + + + get_uri + + + + + + Returns : + a string containing the + gio.File's URI. + + + + + + The get_uri() method gets the URI for the file. + + + This call does no blocking i/o. + + + + + gio.File.get_uri_scheme + + + get_uri_scheme + + + + + + Returns : + a string containing the URI scheme for the + gio.File. + + + + + + The get_uri_scheme() method gets the URI scheme for a + gio.File. + RFC 3986 decodes the scheme as: + + +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + + + Common schemes include "file", "http", "ftp", etc. + + + This call does no blocking i/o. + + + + + gio.File.has_prefix + + + has_prefix + prefix + + + + + prefix : + input gio.File. + + + + Returns : + True if the files's parent, grandparent, + etc is prefix. False otherwise. + + + + + + The has_prefix() method checks whether file has the prefix + specified by prefix. In other word, if the names of inital elements of files pathname + match prefix. Only full pathname elements are matched, so a path like /foo is not + considered a prefix of /foobar, only of /foo/bar. + + + This call does no blocking i/o, as it works purely on names. As such it can sometimes + return False even if file is inside a prefix (from a filesystem point + of view), because the prefix of file is an alias of prefix. + + + + + gio.File.has_uri_scheme + + + has_uri_scheme + uri_scheme + + + + + uri_scheme : + a string containing a URI scheme. + + + + Returns : + True if + gio.File's + backend supports the given URI scheme, False if URI scheme + is None, not supported, or + gio.File is invalid. + + + + + + The has_uri_scheme() method checks to see if a + gio.File + has a given URI scheme. + + + This call does no blocking i/o. + + + + + gio.File.is_native + + + is_native + + + + + + Returns : + True if file is native. + + + + + + The is_native() method checks to see if a file + is native to the platform. + + + A native file s one expressed in the platform-native filename format, e.g. + "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it + might be on a locally mounted remote filesystem. + + + On some systems non-native files may be available using the native filesystem + via a userspace filesystem (FUSE), in these cases this call will return + False, but + gio.File.get_path() + will still return a native path. + + + This call does no blocking i/o. + + + + + gio.File.load_contents + + + load_contents + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a three tuple containing the contents of the file, + the length of the contents of the file and the current entity tag for the file. + + + + + + The load_contents() method loads the content of the file into memory. + The data is always zero-terminated, but this is not included in the resultant length. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.load_contents_async + + + load_contents_async + callback + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The load_contents_async() method starts an asynchronous load of the file's contents. + + + For more details, see + gio.File.load_contents() + which is the synchronous version of this call. + + + When the load operation has completed, callback will be called with user data. To finish + the operation, call + gio.File.load_contents_finish() + with the GAsyncResult returned by the callback. + + + + + gio.File.load_contents_finish + + + load_contents_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a three tuple containing the contents of the file, + the length of the contents of the file and the current entity tag for the file. + + + + + + The load_contents_finish() method finishes an asynchronous + find mount started with + gio.File.load_contents_async(). + + + + + gio.File.make_directory + + + make_directory + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True on successful creation, + False otherwise. + + + + + + The make_directory() method creates a directory. + Note that this will only create a child directory of the immediate parent directory + of the path or URI given by the gio.File. + To recursively create directories, see + gio.File.make_directory_with_parents(). + This function will fail if the parent directory does not exist, setting error to + gio.ERROR_NOT_FOUND. If the file system doesn't support creating directories, this + function will fail, setting error to gio.ERROR_NOT_SUPPORTED. + + + For a local gio.File the newly + created directory will have the default (current) ownership and permissions of the current process. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.make_directory_with_parents + + + make_directory_with_parents + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True if all directories have been successfully created, + False otherwise. + + + + + + The make_directory_with_parents() method creates a directory + and any parent directories that may not exist similar to 'mkdir -p'. If the file system + does not support creating directories, this function will fail, setting error to gio.ERROR_NOT_SUPPORTED. + + + For a local gio.File the newly + created directories will have the default (current) ownership and permissions of the current process. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.make_symbolic_link + + + make_symbolic_link + symlink_value + cancellableNone + + + + + symlink_value : + a string with the value of the new symlink. + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True on the creation of a new symlink, + False otherwise. + + + + + + The make_symbolic_link() method creates a symbolic link. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.monitor + + + monitor + flagsgio.FILE_MONITOR_NONE + cancellableNone + + + + + flags : + + a + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a gio.FileMonitor + for the given file, or None on error + + + + + + The monitor() method obtains a file or directory + monitor for the given file, depending on the type of the file. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.monitor_directory + + + monitor_directory + flagsgio.FILE_MONITOR_NONE + cancellableNone + + + + + flags : + + a + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a gio.FileMonitor + for the given file, or None on error + + + + + + The monitor_directory() method obtains a directory monitor + for the given file. This may fail if directory monitoring is not supported. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.monitor_file + + + monitor_file + flagsgio.FILE_MONITOR_NONE + cancellableNone + + + + + flags : + + a + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a gio.FileMonitor + for the given file, or None on error + + + + + + The monitor_file() method obtains a file monitor for the + given file. If no file notification mechanism exists, then regular polling + of the file is used. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.mount_enclosing_volume + + + mount_enclosing_volume + mount_operation + callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + + + mount_operation : + a + gio.MountOperation + or None to avoid user interaction. + + + + callback : + a GAsyncReadyCallback to call when the request + is satisfied, or None. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to the progress callback function. + + + + + + The mount_enclosing_volume() method starts a mount_operation, + mounting the volume that contains the file location. + + + When this operation has completed, callback will be called with user_user data, + and the operation can be finalized with + gio.File.mount_enclosing_volume_finish(). + + + If cancellable is not None, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.mount_enclosing_volume_finish + + + mount_enclosing_volume_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True if successful. If an error has occurred, + this function will return False and set error appropriately if present. + + + + + + The mount_enclosing_volume_finish() method finishes an asynchronous + find mount started with + gio.File.mount_enclosing_volume(). + + + + + gio.File.mount_mountable + + + mount_mountable + mount_operation + callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + + + mount_operation : + a + gio.MountOperation + or None to avoid user interaction. + + + + callback : + a GAsyncReadyCallback to call when the request + is satisfied, or None. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to the progress callback function. + + + + + + The mount_mountable() method mounts a file of type + gio.FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when, + for instance, passwords are needed during authentication. + + + When this operation has completed, callback will be called with user_user data, + and the operation can be finalized with + gio.File.mount_mountable_finish(). + + + If cancellable is not None, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.mount_mountable_finish + + + mount_mountable_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a gio.File + or None on error. + + + + + + The mount_mountable_finish() method finishes an asynchronous + find mount started with + gio.File.mount_mountable(). + + + + + gio.File.move + + + copy + destination + progress_callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + + + destination : + destination gio.File. + + + + progress_callback : + function to callback with progress information. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to the progress callback function. + + + + Returns : + True on success, + False otherwise. + + + + + + The move() method tries to move the file or directory + source to the location specified by destination. If native move operations are + supported then this is used, otherwise a copy + delete fallback is used. The native + implementation may support moving directories (for instance on moves inside the same + filesystem), but the fallback code does not. + + + If the flag gio.FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten. + + + If the flag gio.FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied + as symlinks, otherwise the target of the source symlink will be copied. + + + If cancellable is not None, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + + + If progress_callback is not None, then the operation can be monitored + by setting this to a GFileProgressCallback function. progress_callback_data will be passed + to this function. It is guaranteed that this callback will be called after all data has been + transferred with the total number of bytes copied during the operation. + + + If the source file does not exist then the gio.ERROR_NOT_FOUND error is returned, + independent on the status of the destination. + + + If gio.FILE_COPY_OVERWRITE is not specified and the target exists, then the error + gio.ERROR_EXISTS is returned. + + + If trying to overwrite a file over a directory the gio.ERROR_IS_DIRECTORY error is returned. + If trying to overwrite a directory with a directory the gio.ERROR_WOULD_MERGE error is returned. + + + If the source is a directory and the target does not exist, or gio.FILE_COPY_OVERWRITE is specified + and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error may be returned + (if the native move operation isn't available). + + + + + gio.File.query_default_handler + + + query_default_handler + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a gio.AppInfo + if the handle was found, None if there were errors. + + + + + + The query_default_handler() method returns the + gio.AppInfo that + is registered as the default application to handle the file specified by file. + + + If cancellable is not None, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + + + + + gio.File.query_exists + + + query_exists + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True if the file exists (and can be detected + without error), False otherwise (or if cancelled). + + + + + + The query_exists() method is an tility function to check + if a particular file exists. This is implemented using + gio.File.query_info() + and as such does blocking I/O. + + + Note that in many cases it is racy to first check for file existence and then execute + something based on the outcome of that, because the file might have been created or + removed in between the operations. The general approach to handling that is to not check, + but just do the operation and handle the errors as they come. + + + As an example of race-free checking, take the case of reading a file, and if it doesn't + exist, creating it. There are two racy versions: read it, and on error create it; and: + check if it exists, if not create it. These can both result in two processes creating the + file (with perhaps a partially written file as the result). The correct approach is to + always try to create the file with + gio.File.create() + which will either atomically create the file or fail with a gio.ERROR_EXISTS error. + + + However, in many cases an existence check is useful in a user interface, for instance + to make a menu item sensitive/insensitive, so that you don't have to fool users that + something is possible and then just show and error dialog. If you do this, you should + make sure to also handle the errors that can happen due to races when you execute the operation. + + + + + gio.File.query_file_type + + + query_file_type + flagsgio.FILE_MONITOR_NONE + cancellableNone + + + + + flags : + + a + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + + + + + + + + The query_file_type() method it's an utility function to inspect + the + of a file. This is implemented using + gio.File.query_info() + and as such does blocking I/O. + + + The primary use case of this method is to check if a file is a regular file, directory, or symlink. + + + + + gio.File.query_filesystem_info + + + query_filesystem_info + attributes + cancellableNone + + + + + attributes : + an attribute query string. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a gio.FileInfo + or None if there was an error. + + + + + + The query_filesystem_info() method it's similar to + gio.File.query_info(), + but obtains information about the filesystem the file is on, rather than the + file itself. For instance the amount of space available and the type of the filesystem. + + + The attribute value is a string that specifies the file attributes that should be gathered. + It is not an error if it's not possible to read a particular requested attribute from a file - + it just won't be set. attribute should be a comma-separated list of attribute or attribute + wildcards. The wildcard "*" means all attributes, and a wildcard like "fs:*" means all attributes + in the fs namespace. The standard namespace for filesystem attributes is "fs". Common attributes + of interest are gio.FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), + gio.FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and gio.FILE_ATTRIBUTE_FILESYSTEM_TYPE + (type of the filesystem). + + + If cancellable is not None, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.IO_ERROR_CANCELLED will be returned. + + + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. Other errors + are possible too, and depend on what kind of filesystem the file is on. + + -- cgit