Gio.File¶

interface

GFile is a high level abstraction for manipulating files on a virtual file system. GFiles are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that GFile objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see InputStream and OutputStream).

To construct a GFile, you can use:

File.new_for_path if you have a path.
File.new_for_uri if you have a URI.
File.new_for_commandline_arg or File.new_for_commandline_arg_and_cwd for a command line argument.
File.new_tmp to create a temporary file from a template.
File.new_tmp_async to asynchronously create a temporary file.
File.new_tmp_dir_async to asynchronously create a temporary directory.
File.parse_name from a UTF-8 string gotten from File.get_parse_name.
File.new_build_filename or File.new_build_filenamev to create a file from path elements.

One way to think of a GFile is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as GFiles are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.

GFiles make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with GFile using File.get_parent to get an identifier for the parent directory, File.get_child to get a child within a directory, and File.resolve_relative_path to resolve a relative path between two GFiles. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call File.get_parent on two different files.

All GFiles have a basename (get with File.get_basename). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with File.query_info. This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the GFile to use to actually access the file, because there is no way to go from a display name to the actual name.

Using GFile as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different GFiles to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two GFiles point to the same file you can query for the G_FILE_ATTRIBUTE_ID_FILE attribute. Note that GFile does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, . or .. path segments, etc) does not create different GFiles.

Many GFile operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have _async() appended to their function names. The asynchronous I/O functions call a AsyncReadyCallback which is then used to finalize the operation, producing a AsyncResult which is then passed to the function’s matching _finish() operation.

It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the introduction to asynchronous programming section for more.

Some GFile operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include:

File.mount_mountable to mount a mountable file.
File.unmount_mountable_with_operation to unmount a mountable file.
File.eject_mountable_with_operation to eject a mountable file.

Entity Tags¶

One notable feature of GFiles are entity tags, or ‘etags’ for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the description of HTTP ETags in RFC9110. GFile Entity Tags are a very similar concept.

Methods¶

append_to¶

def append_to(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Gets an output stream for appending data to the file. If the file doesn't already exist it is created.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error. If the file is a directory the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

append_to_async¶

def append_to_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for appending.

For more details, see File.append_to which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.append_to_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

append_to_finish¶

def append_to_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file append operation started with File.append_to_async.

Parameters:

res — AsyncResult

build_attribute_list_for_copy¶

def build_attribute_list_for_copy(self, flags: FileCopyFlags | int, cancellable: Cancellable | None = ...) -> str

Prepares the file attribute query string for copying to file.

This function prepares an attribute query string to be passed to File.query_info to get a list of attributes normally copied with the file (see File.copy_attributes for the detailed description). This function is used by the implementation of File.copy_attributes and is useful when one needs to query and set the attributes in two stages (e.g., for recursive move of a directory).

Parameters:

flags — a set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore

copy¶

def copy(self, destination: File, flags: FileCopyFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ...) -> bool

Copies the file source to the location specified by destination. Can not handle recursive copies of directories.

If the flag FileCopyFlags.OVERWRITE is specified an already existing destination file is overwritten.

If the flag FileCopyFlags.NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.

If the flag FileCopyFlags.ALL_METADATA is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see FileInfo).

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 IOErrorEnum.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 IOErrorEnum.NOT_FOUND error is returned, independent on the status of the destination.

If FileCopyFlags.OVERWRITE is not specified and the target exists, then the error IOErrorEnum.EXISTS is returned.

If trying to overwrite a file over a directory, the IOErrorEnum.IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the IOErrorEnum.WOULD_MERGE error is returned.

If the source is a directory and the target does not exist, or FileCopyFlags.OVERWRITE is specified and the target is a file, then the IOErrorEnum.WOULD_RECURSE error is returned.

If you are interested in copying the File object itself (not the on-disk file), see File.dup.

Parameters:

destination — destination File
flags — set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore
progress_callback — function to callback with progress information, or None if progress information is not needed

copy_async¶

def copy_async(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Copies the file source to the location specified by destination asynchronously. For details of the behaviour, see File.copy.

If progress_callback is not None, then that function that will be called just like in File.copy. The callback will run in the default main context of the thread calling File.copy_async — the same context as callback is run in.

When the operation is finished, callback will be called. You can then call File.copy_finish to get the result of the operation.

Parameters:

destination — destination File
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
progress_callback — function to callback with progress information, or None if progress information is not needed
callback — a GAsyncReadyCallback to call when the request is satisfied

copy_async_with_closures¶

def copy_async_with_closures(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None, progress_callback_closure: GObject.Closure | None, ready_callback_closure: GObject.Closure) -> None

Version of File.copy_async using closures instead of callbacks for easier binding in other languages.

Parameters:

destination — destination File
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, NULL to ignore
progress_callback_closure — GObject.Closure to invoke with progress information, or NULL if progress information is not needed
ready_callback_closure — GObject.Closure to invoke when the request is satisfied

copy_attributes¶

def copy_attributes(self, destination: File, flags: FileCopyFlags | int, cancellable: Cancellable | None = ...) -> bool

Copies the file attributes from source to destination.

Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation (which for instance does not include e.g. owner). However if FileCopyFlags.ALL_METADATA is specified in flags, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source.

Parameters:

destination — a File to copy attributes to
flags — a set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore

copy_finish¶

def copy_finish(self, res: AsyncResult) -> bool

Finishes copying the file started with File.copy_async.

Parameters:

res — a AsyncResult

create¶

def create(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Creates a new file and returns an output stream for writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If a file or directory with this name already exists the IOErrorEnum.EXISTS error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is to long IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

create_async¶

def create_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.

For more details, see File.create which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.create_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

create_finish¶

def create_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file create operation started with File.create_async.

Parameters:

res — a AsyncResult

create_readwrite¶

def create_readwrite(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileIOStream

Creates a new file and returns a stream for reading and writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If a file or directory with this name already exists, the IOErrorEnum.EXISTS error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is too long, IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

create_readwrite_async¶

def create_readwrite_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.

For more details, see File.create_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.create_readwrite_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

create_readwrite_finish¶

def create_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file create operation started with File.create_readwrite_async.

Parameters:

res — a AsyncResult

delete¶

def delete(self, cancellable: Cancellable | None = ...) -> bool

Deletes a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as GLib.unlink.

If file doesn’t exist, IOErrorEnum.NOT_FOUND will be returned. This allows for deletion to be implemented avoiding time-of-check to time-of-use races:

g_autoptr(GError) local_error = NULL;
if (!g_file_delete (my_file, my_cancellable, &local_error) &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
  {
    // deletion failed for some reason other than the file not existing:
    // so report the error
    g_warning ("Failed to delete %s: %s",
               g_file_peek_path (my_file), local_error->message);
  }

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

delete_async¶

def delete_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously delete a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as GLib.unlink.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

delete_finish¶

def delete_finish(self, result: AsyncResult) -> bool

Finishes deleting a file started with File.delete_async.

Parameters:

result — a AsyncResult

dup¶

def dup(self) -> File

Duplicates a File handle. This operation does not duplicate the actual file or directory represented by the File; see File.copy if attempting to copy a file.

File.dup is useful when a second handle is needed to the same underlying file, for use in a separate thread (File is not thread-safe). For use within the same thread, use GObject.Object.ref to increment the existing object’s reference count.

This call does no blocking I/O.

eject_mountable¶

def eject_mountable(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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

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 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

eject_mountable_finish¶

def eject_mountable_finish(self, result: AsyncResult) -> bool

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

Finishes an asynchronous eject operation started by File.eject_mountable.

Parameters:

result — a AsyncResult

eject_mountable_with_operation¶

def eject_mountable_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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 File.eject_mountable_with_operation_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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

eject_mountable_with_operation_finish¶

def eject_mountable_with_operation_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous eject operation started by File.eject_mountable_with_operation.

Parameters:

result — a AsyncResult

enumerate_children¶

def enumerate_children(self, attributes: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> FileEnumerator

Gets the requested information about the files in a directory. The result is a FileEnumerator object that will give out FileInfo objects for all the files in the directory.

The attributes 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. attributes should be a comma-separated list of attributes 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 FILE_ATTRIBUTE_STANDARD_NAME. FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call FileEnumerator.get_child or FileEnumerator.iterate on the returned enumerator.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is not a directory, the IOErrorEnum.NOT_DIRECTORY error will be returned. Other errors are possible too.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

enumerate_children_async¶

def enumerate_children_async(self, attributes: str, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about the files in a directory. The result is a FileEnumerator object that will give out FileInfo objects for all the files in the directory.

For more details, see File.enumerate_children which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.enumerate_children_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

enumerate_children_finish¶

def enumerate_children_finish(self, res: AsyncResult) -> FileEnumerator

Finishes an async enumerate children operation. See File.enumerate_children_async.

Parameters:

res — a AsyncResult

equal¶

def equal(self, file2: File) -> bool

Checks if the two given GFiles refer to the same file.

This function can be used with File.hash to insert Files efficiently in a hash table.

Note that two GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. For local files, this function essentially compares the file paths, so two Files which point to different hard or soft links will not be considered equal, despite pointing to the same content.

For determining whether two files are hardlinked, see FILE_ATTRIBUTE_ID_FILE.

This call does no blocking I/O.

Parameters:

file2 — the second File

find_enclosing_mount¶

def find_enclosing_mount(self, cancellable: Cancellable | None = ...) -> Mount

Gets a Mount for the File.

Mount is returned only for user interesting locations, see VolumeMonitor. If the FileIface for file does not have a #mount, error will be set to IOErrorEnum.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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

find_enclosing_mount_async¶

def find_enclosing_mount_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the mount for the file.

For more details, see File.find_enclosing_mount which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.find_enclosing_mount_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

find_enclosing_mount_finish¶

def find_enclosing_mount_finish(self, res: AsyncResult) -> Mount

Finishes an asynchronous find mount request. See File.find_enclosing_mount_async.

Parameters:

res — a AsyncResult

get_basename¶

def get_basename(self) -> str | None

Gets the base name (the last component of the path) for a given 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 FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with File.query_info.

This call does no blocking I/O.

get_child¶

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

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 File that points to it. You can use this for instance to create that file.

This call does no blocking I/O.

Parameters:

name — string containing the child's basename

get_child_for_display_name¶

def get_child_for_display_name(self, display_name: str) -> File

Gets the child of file for a given display_name (i.e. a UTF-8 version of the name). If this function fails, it returns None and error will be set. This is very useful when constructing a File 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.

Parameters:

display_name — string to a possible child

get_parent¶

def get_parent(self) -> File | None

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.

get_parse_name¶

def get_parse_name(self) -> str

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 File back using File.parse_name.

This is generally used to show the 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 UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped).

This call does no blocking I/O.

get_path¶

def get_path(self) -> str | None

Gets the local pathname for File, if one exists. If non-None, this is guaranteed to be an absolute, canonical path. It might contain symlinks.

This call does no blocking I/O.

get_relative_path¶

def get_relative_path(self, descendant: File) -> str | None

Gets the path for descendant relative to parent.

This call does no blocking I/O.

Parameters:

descendant — input File

get_uri¶

def get_uri(self) -> str

Gets the URI for the file.

This call does no blocking I/O.

get_uri_scheme¶

def get_uri_scheme(self) -> str | None

Gets the URI scheme for a File. RFC 3986 decodes the scheme as:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include "file", "http", "ftp", etc.

The scheme can be different from the one used to construct the File, in that it might be replaced with one that is logically equivalent to the File.

This call does no blocking I/O.

has_parent¶

def has_parent(self, parent: File | None = ...) -> bool

Checks if file has a parent, and optionally, if it is parent.

If parent is None then this function returns True if file has any parent at all. If parent is non-None then True is only returned if file is an immediate child of parent.

Parameters:

parent — the parent to check for, or None

has_prefix¶

def has_prefix(self, prefix: File) -> bool

Checks whether file has the prefix specified by prefix.

In other words, if the names of initial elements of file's 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.

A File is not a prefix of itself. If you want to check for equality, use File.equal.

This call does no 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.

Parameters:

prefix — input File

has_uri_scheme¶

def has_uri_scheme(self, uri_scheme: str) -> bool

Checks to see if a File has a given URI scheme.

This call does no blocking I/O.

Parameters:

uri_scheme — a string containing a URI scheme

hash¶

def hash(self) -> int

Creates a hash value for a File.

This call does no blocking I/O.

is_native¶

def is_native(self) -> bool

Checks to see if a file is native to the platform.

A native file is 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 File.get_path will still return a native path.

This call does no blocking I/O.

load_bytes¶

def load_bytes(self, cancellable: Cancellable | None = ...) -> tuple[bytes, str]

Loads the contents of file and returns it as GLib.Bytes.

If file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling File.load_contents and GLib.Bytes.new_take.

For resources, etag_out will be set to None.

The data contained in the resulting GLib.Bytes is always zero-terminated, but this is not included in the GLib.Bytes length. The resulting GLib.Bytes should be freed with GLib.Bytes.unref when no longer in use.

Parameters:

cancellable — a Cancellable or None

load_bytes_async¶

def load_bytes_async(self, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously loads the contents of file as GLib.Bytes.

If file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling File.load_contents_async and GLib.Bytes.new_take.

callback should call File.load_bytes_finish to get the result of this asynchronous operation.

See File.load_bytes for more information.

Parameters:

cancellable — a Cancellable or None
callback — a GAsyncReadyCallback to call when the request is satisfied

load_bytes_finish¶

def load_bytes_finish(self, result: AsyncResult) -> tuple[bytes, str]

Completes an asynchronous request to File.load_bytes_async.

For resources, etag_out will be set to None.

The data contained in the resulting GLib.Bytes is always zero-terminated, but this is not included in the GLib.Bytes length. The resulting GLib.Bytes should be freed with GLib.Bytes.unref when no longer in use.

See File.load_bytes for more information.

Parameters:

result — a AsyncResult provided to the callback

load_contents¶

def load_contents(self, cancellable: Cancellable | None = ...) -> tuple[bool, list[int], str]

Loads the content of the file into memory. The data is always zero-terminated, but this is not included in the resultant length. The returned contents should be freed with GLib.free when no longer needed.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

load_contents_async¶

def load_contents_async(self, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Starts an asynchronous load of the file's contents.

For more details, see 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 File.load_contents_finish with the AsyncResult returned by the callback.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

load_contents_finish¶

def load_contents_finish(self, res: AsyncResult) -> tuple[bool, list[int], str]

Finishes an asynchronous load of the file's contents. The contents are placed in contents, and length is set to the size of the contents string. The contents should be freed with GLib.free when no longer needed. If etag_out is present, it will be set to the new entity tag for the file.

Parameters:

res — a AsyncResult

load_partial_contents_finish¶

def load_partial_contents_finish(self, res: AsyncResult) -> tuple[bool, list[int], str]

Finishes an asynchronous partial load operation that was started with g_file_load_partial_contents_async(). The data is always zero-terminated, but this is not included in the resultant length. The returned contents should be freed with GLib.free when no longer needed.

Parameters:

res — a AsyncResult

make_directory¶

def make_directory(self, cancellable: Cancellable | None = ...) -> bool

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 File. To recursively create directories, see File.make_directory_with_parents.

This function will fail if the parent directory does not exist, setting error to IOErrorEnum.NOT_FOUND. If the file system doesn't support creating directories, this function will fail, setting error to IOErrorEnum.NOT_SUPPORTED. If the directory already exists, IOErrorEnum.EXISTS will be returned.

For a local 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

make_directory_async¶

def make_directory_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a directory.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

make_directory_finish¶

def make_directory_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous directory creation, started with File.make_directory_async.

Parameters:

result — a AsyncResult

make_directory_with_parents¶

def make_directory_with_parents(self, cancellable: Cancellable | None = ...) -> bool

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 IOErrorEnum.NOT_SUPPORTED. If the directory itself already exists, this function will fail setting error to IOErrorEnum.EXISTS, unlike the similar GLib.mkdir_with_parents.

For a local 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

make_symbolic_link¶

def make_symbolic_link(self, symlink_value: str | bytes | os.PathLike[str] | os.PathLike[bytes], cancellable: Cancellable | None = ...) -> bool

Creates a symbolic link named file which contains the string symlink_value.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

symlink_value — a string with the path for the target of the new symlink
cancellable — optional Cancellable object, None to ignore

make_symbolic_link_async¶

def make_symbolic_link_async(self, symlink_value: str | bytes | os.PathLike[str] | os.PathLike[bytes], io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a symbolic link named file which contains the string symlink_value.

Parameters:

symlink_value — a string with the path for the target of the new symlink
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

make_symbolic_link_finish¶

def make_symbolic_link_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous symbolic link creation, started with File.make_symbolic_link_async.

Parameters:

result — a AsyncResult

measure_disk_usage¶

def measure_disk_usage(self, flags: FileMeasureFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileMeasureProgressCallback | None = ...) -> tuple[bool, int, int, int]

Recursively measures the disk usage of file.

This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links).

By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless FileMeasureFlags.REPORT_ANY_ERROR is given in flags.

The returned size, disk_usage, is in bytes and should be formatted with GLib.format_size in order to get something reasonable for showing in a user interface.

progress_callback and progress_data can be given to request periodic progress updates while scanning. See the documentation for GFileMeasureProgressCallback for information about when and how the callback will be invoked.

Parameters:

flags — FileMeasureFlags
cancellable — optional Cancellable
progress_callback — a GFileMeasureProgressCallback

measure_disk_usage_finish¶

def measure_disk_usage_finish(self, result: AsyncResult) -> tuple[bool, int, int, int]

Collects the results from an earlier call to g_file_measure_disk_usage_async(). See File.measure_disk_usage for more information.

Parameters:

result — the AsyncResult passed to your GAsyncReadyCallback

monitor¶

def monitor(self, flags: FileMonitorFlags | int, cancellable: Cancellable | None = ...) -> FileMonitor

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — a set of FileMonitorFlags
cancellable — optional Cancellable object, None to ignore

monitor_directory¶

def monitor_directory(self, flags: FileMonitorFlags | int, cancellable: Cancellable | None = ...) -> FileMonitor

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 IOErrorEnum.CANCELLED will be returned.

It does not make sense for flags to contain FileMonitorFlags.WATCH_HARD_LINKS, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with File.monitor.

Parameters:

flags — a set of FileMonitorFlags
cancellable — optional Cancellable object, None to ignore

monitor_file¶

def monitor_file(self, flags: FileMonitorFlags | int, cancellable: Cancellable | None = ...) -> FileMonitor

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 IOErrorEnum.CANCELLED will be returned.

If flags contains FileMonitorFlags.WATCH_HARD_LINKS then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the FileMonitor backend and/or filesystem type.

Parameters:

flags — a set of FileMonitorFlags
cancellable — optional Cancellable object, None to ignore

mount_enclosing_volume¶

def mount_enclosing_volume(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

mount_enclosing_volume_finish¶

def mount_enclosing_volume_finish(self, result: AsyncResult) -> bool

Finishes a mount operation started by File.mount_enclosing_volume.

Parameters:

result — a AsyncResult

mount_mountable¶

def mount_mountable(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when, for instance, passwords are needed during authentication.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

mount_mountable_finish¶

def mount_mountable_finish(self, result: AsyncResult) -> File

Finishes a mount operation. See File.mount_mountable for details.

Finish an asynchronous mount operation that was started with File.mount_mountable.

Parameters:

result — a AsyncResult

move¶

def move(self, destination: File, flags: FileCopyFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ...) -> bool

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 FileCopyFlags.OVERWRITE is specified an already existing destination file is overwritten.

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 IOErrorEnum.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 IOErrorEnum.NOT_FOUND error is returned, independent on the status of the destination.

If FileCopyFlags.OVERWRITE is not specified and the target exists, then the error IOErrorEnum.EXISTS is returned.

If trying to overwrite a file over a directory, the IOErrorEnum.IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the IOErrorEnum.WOULD_MERGE error is returned.

If the source is a directory and the target does not exist, or FileCopyFlags.OVERWRITE is specified and the target is a file, then the IOErrorEnum.WOULD_RECURSE error may be returned (if the native move operation isn't available).

Parameters:

destination — File pointing to the destination location
flags — set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore
progress_callback — GFileProgressCallback function for updates

move_async¶

def move_async(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously moves a file source to the location of destination. For details of the behaviour, see File.move.

If progress_callback is not None, then that function that will be called just like in File.move. The callback will run in the default main context of the thread calling File.move_async — the same context as callback is run in.

When the operation is finished, callback will be called. You can then call File.move_finish to get the result of the operation.

Parameters:

destination — File pointing to the destination location
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
progress_callback — GFileProgressCallback function for updates
callback — a GAsyncReadyCallback to call when the request is satisfied

move_async_with_closures¶

def move_async_with_closures(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None, progress_callback_closure: GObject.Closure | None, ready_callback_closure: GObject.Closure) -> None

Version of File.move_async using closures instead of callbacks for easier binding in other languages.

Parameters:

destination — destination File
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, NULL to ignore
progress_callback_closure — GObject.Closure to invoke with progress information, or NULL if progress information is not needed
ready_callback_closure — GObject.Closure to invoke when the request is satisfied

move_finish¶

def move_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous file movement, started with File.move_async.

Parameters:

result — a AsyncResult

open_readwrite¶

def open_readwrite(self, cancellable: Cancellable | None = ...) -> FileIOStream

Opens an existing file for reading and writing. The result is a FileIOStream that can be used to read and write the contents 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is a directory, the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

cancellable — a Cancellable

open_readwrite_async¶

def open_readwrite_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for reading and writing.

For more details, see File.open_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.open_readwrite_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

open_readwrite_finish¶

def open_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file read operation started with File.open_readwrite_async.

Parameters:

res — a AsyncResult

peek_path¶

def peek_path(self) -> str | None

Exactly like File.get_path, but caches the result via g_object_set_qdata_full(). This is useful for example in C applications which mix g_file_* APIs with native ones. It also avoids an extra duplicated string when possible, so will be generally more efficient.

This call does no blocking I/O.

poll_mountable¶

def poll_mountable(self, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Polls a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

poll_mountable_finish¶

def poll_mountable_finish(self, result: AsyncResult) -> bool

Finishes a poll operation. See File.poll_mountable for details.

Finish an asynchronous poll operation that was polled with File.poll_mountable.

Parameters:

result — a AsyncResult

query_default_handler¶

def query_default_handler(self, cancellable: Cancellable | None = ...) -> AppInfo

Returns the 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

query_default_handler_async¶

def query_default_handler_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Async version of File.query_default_handler.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is done

query_default_handler_finish¶

def query_default_handler_finish(self, result: AsyncResult) -> AppInfo

Finishes a File.query_default_handler_async operation.

Parameters:

result — a AsyncResult

query_exists¶

def query_exists(self, cancellable: Cancellable | None = ...) -> bool

Utility function to check if a particular file exists.

The fallback implementation of this API is using File.query_info and therefore may do blocking I/O. To asynchronously query the existence of a file, use File.query_info_async.

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 File.create which will either atomically create the file or fail with a IOErrorEnum.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 an 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.

Parameters:

cancellable — optional Cancellable object, None to ignore

query_file_type¶

def query_file_type(self, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> FileType

Utility function to inspect the FileType of a file. This is implemented using 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.

Parameters:

flags — a set of FileQueryInfoFlags passed to File.query_info
cancellable — optional Cancellable object, None to ignore

query_filesystem_info¶

def query_filesystem_info(self, attributes: str, cancellable: Cancellable | None = ...) -> FileInfo

Similar to 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 attributes value is a string that specifies the 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. attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

attributes — an attribute query string
cancellable — optional Cancellable object, None to ignore

query_filesystem_info_async¶

def query_filesystem_info_async(self, attributes: str, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about the filesystem that the specified file is on. The result is a FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see File.query_filesystem_info which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.query_info_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

query_filesystem_info_finish¶

def query_filesystem_info_finish(self, res: AsyncResult) -> FileInfo

Finishes an asynchronous filesystem info query. See File.query_filesystem_info_async.

Parameters:

res — a AsyncResult

query_info¶

def query_info(self, attributes: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> FileInfo

Gets the requested information about specified file.

The result is a FileInfo object that contains key-value attributes (such as the type or size of the file).

The attributes 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. In particular this means that if a file is inaccessible (due to being in a folder with restrictive permissions), for example, you can expect the returned FileInfo to have very few attributes set. You should check whether an attribute is set using FileInfo.has_attribute before trying to retrieve its value.

It is guaranteed that if any of the following attributes are listed in attributes, they will always be set in the returned FileInfo, even if the user doesn’t have permissions to access the file:

attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "\*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query might be "standard::*,owner::user". The standard attributes are available as defines, like FILE_ATTRIBUTE_STANDARD_NAME.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass FileQueryInfoFlags.NOFOLLOW_SYMLINKS in flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of file system the file is on.

Parameters:

attributes — an attribute query string
flags — flags to affect the query operation
cancellable — optional cancellable object

query_info_async¶

def query_info_async(self, attributes: str, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about specified file. The result is a FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see File.query_info which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.query_info_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

query_info_finish¶

def query_info_finish(self, res: AsyncResult) -> FileInfo

Finishes an asynchronous file info query. See File.query_info_async.

Parameters:

res — a AsyncResult

query_settable_attributes¶

def query_settable_attributes(self, cancellable: Cancellable | None = ...) -> FileAttributeInfoList

Obtain the list of settable attributes for the file.

Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

query_writable_namespaces¶

def query_writable_namespaces(self, cancellable: Cancellable | None = ...) -> FileAttributeInfoList

Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace).

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

read¶

def read(self, cancellable: Cancellable | None = ...) -> FileInputStream

Opens a file for reading. The result is a FileInputStream that can be used to read the contents 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is a directory, the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

cancellable — a Cancellable

read_async¶

def read_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for reading.

For more details, see File.read which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.read_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

read_finish¶

def read_finish(self, res: AsyncResult) -> FileInputStream

Finishes an asynchronous file read operation started with File.read_async.

Parameters:

res — a AsyncResult

replace¶

def replace(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If you pass in a non-None etag value and file already exists, then this value is compared to the current entity tag of the file, and if they differ an IOErrorEnum.WRONG_ETAG error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from FileOutputStream.get_etag after you've finished writing and closed the FileOutputStream. When you load a new file you can use FileInputStream.query_info to get the etag of the file.

If make_backup is True, this function will attempt to make a backup of the current file before overwriting it. If this fails a IOErrorEnum.CANT_CREATE_BACKUP error will be returned. If you want to replace anyway, try again with make_backup set to False.

If the file is a directory the IOErrorEnum.IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a IOErrorEnum.NOT_REGULAR_FILE error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is to long IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

etag — an optional entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

replace_async¶

def replace_async(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.

For more details, see File.replace which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.replace_finish to get the result of the operation.

Parameters:

etag — an entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

replace_contents¶

def replace_contents(self, contents: list[int], etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> tuple[bool, str]

Replaces the contents of file with contents of length bytes.

If etag is specified (not None), any existing file must have that etag, or the error IOErrorEnum.WRONG_ETAG will be returned.

If make_backup is True, this function will attempt to make a backup of file. Internally, it uses File.replace, so will try to replace the file contents in the safest way possible. For example, atomic renames are used when replacing local files’ contents.

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 IOErrorEnum.CANCELLED will be returned.

The returned new_etag can be used to verify that the file hasn't changed the next time it is saved over.

Parameters:

contents — a string containing the new contents for file
etag — the old entity-tag for the document, or None
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

replace_contents_async¶

def replace_contents_async(self, contents: list[int], etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Starts an asynchronous replacement of file with the given contents of length bytes. etag will replace the document's current entity tag.

When this operation has completed, callback will be called with user_user data, and the operation can be finalized with File.replace_contents_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 IOErrorEnum.CANCELLED will be returned.

If make_backup is True, this function will attempt to make a backup of file.

Note that no copy of contents will be made, so it must stay valid until callback is called. See File.replace_contents_bytes_async for a GLib.Bytes version that will automatically hold a reference to the contents (without copying) for the duration of the call.

Parameters:

contents — string of contents to replace the file with
etag — a new entity tag for the file, or None
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

replace_contents_bytes_async¶

def replace_contents_bytes_async(self, contents: bytes, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Same as File.replace_contents_async but takes a GLib.Bytes input instead. This function will keep a ref on contents until the operation is done. Unlike File.replace_contents_async this allows forgetting about the content without waiting for the callback.

When this operation has completed, callback will be called with user_user data, and the operation can be finalized with File.replace_contents_finish.

Parameters:

contents — a GLib.Bytes
etag — a new entity tag for the file, or None
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

replace_contents_finish¶

def replace_contents_finish(self, res: AsyncResult) -> tuple[bool, str]

Finishes an asynchronous replace of the given file. See File.replace_contents_async. Sets new_etag to the new entity tag for the document, if present.

Parameters:

res — a AsyncResult

replace_finish¶

def replace_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file replace operation started with File.replace_async.

Parameters:

res — a AsyncResult

replace_readwrite¶

def replace_readwrite(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileIOStream

Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

For details about the behaviour, see File.replace which does the same thing but returns an output stream only.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

etag — an optional entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

replace_readwrite_async¶

def replace_readwrite_async(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first.

For more details, see File.replace_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.replace_readwrite_finish to get the result of the operation.

Parameters:

etag — an entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

replace_readwrite_finish¶

def replace_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file replace operation started with File.replace_readwrite_async.

Parameters:

res — a AsyncResult

resolve_relative_path¶

def resolve_relative_path(self, relative_path: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> File

Resolves a relative path for file to an absolute path.

This call does no blocking I/O.

If the relative_path is an absolute path name, the resolution is done absolutely (without taking file path as base).

Parameters:

relative_path — a given relative path string

set_attribute¶

def set_attribute(self, attribute: str, type: FileAttributeType | int, value_p: int | None, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets an attribute in the file with attribute name attribute to value_p.

Some attributes can be unset by setting type to FileAttributeType.INVALID and value_p to None.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
type — The type of the attribute
value_p — a pointer to the value (or the pointer itself if the type is a pointer type)
flags — a set of FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_byte_string¶

def set_attribute_byte_string(self, attribute: str, value: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.BYTE_STRING to value. If attribute is of a different type, this operation will fail, returning False.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a string containing the attribute's new value
flags — a FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_int32¶

def set_attribute_int32(self, attribute: str, value: int, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.INT32 to value. If attribute is of a different type, this operation will fail.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a #gint32 containing the attribute's new value
flags — a FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_int64¶

def set_attribute_int64(self, attribute: str, value: int, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.INT64 to value. If attribute is of a different type, this operation will fail.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a #guint64 containing the attribute's new value
flags — a FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_string¶

def set_attribute_string(self, attribute: str, value: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.STRING to value. If attribute is of a different type, this operation will fail.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a string containing the attribute's value
flags — FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_uint32¶

def set_attribute_uint32(self, attribute: str, value: int, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.UINT32 to value. If attribute is of a different type, this operation will fail.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a #guint32 containing the attribute's new value
flags — a FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attribute_uint64¶

def set_attribute_uint64(self, attribute: str, value: int, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets attribute of type FileAttributeType.UINT64 to value. If attribute is of a different type, this operation will fail.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
value — a #guint64 containing the attribute's new value
flags — a FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_attributes_async¶

def set_attributes_async(self, info: FileInfo, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sets the attributes of file with info.

For more details, see File.set_attributes_from_info, which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.set_attributes_finish to get the result of the operation.

Parameters:

info — a FileInfo
flags — a FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

set_attributes_finish¶

def set_attributes_finish(self, result: AsyncResult) -> tuple[bool, FileInfo]

Finishes setting an attribute started in File.set_attributes_async.

Parameters:

result — a AsyncResult

set_attributes_from_info¶

def set_attributes_from_info(self, info: FileInfo, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Tries to set all attributes in the FileInfo on the target values, not stopping on the first error.

If there is any error during this operation then error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to FileAttributeStatus.ERROR_SETTING, which means you can also detect further errors.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

info — a FileInfo
flags — FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

set_display_name¶

def set_display_name(self, display_name: str, cancellable: Cancellable | None = ...) -> File

Renames file to the specified display name.

The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the file is renamed to this.

If you want to implement a rename operation in the user interface the edit name (FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to File.set_display_name.

On success the resulting converted filename is 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

display_name — a string
cancellable — optional Cancellable object, None to ignore

set_display_name_async¶

def set_display_name_async(self, display_name: str, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sets the display name for a given File.

For more details, see File.set_display_name which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.set_display_name_finish to get the result of the operation.

Parameters:

display_name — a string
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

set_display_name_finish¶

def set_display_name_finish(self, res: AsyncResult) -> File

Finishes setting a display name started with File.set_display_name_async.

Parameters:

res — a AsyncResult

start_mountable¶

def start_mountable(self, flags: DriveStartFlags | int, start_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Starts a file of type FileType.MOUNTABLE. Using start_operation, you can request callbacks when, for instance, passwords are needed during authentication.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
start_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

start_mountable_finish¶

def start_mountable_finish(self, result: AsyncResult) -> bool

Finishes a start operation. See File.start_mountable for details.

Finish an asynchronous start operation that was started with File.start_mountable.

Parameters:

result — a AsyncResult

stop_mountable¶

def stop_mountable(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Stops a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.stop_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction.
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

stop_mountable_finish¶

def stop_mountable_finish(self, result: AsyncResult) -> bool

Finishes a stop operation, see File.stop_mountable for details.

Finish an asynchronous stop operation that was started with File.stop_mountable.

Parameters:

result — a AsyncResult

supports_thread_contexts¶

def supports_thread_contexts(self) -> bool

Checks if file supports thread-default main contexts (see GLib.MainContext.push_thread_default) If this returns False, you cannot perform asynchronous operations on file in a thread that has a thread-default context.

trash¶

def trash(self, cancellable: Cancellable | None = ...) -> bool

Sends file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Trashing is disabled for system mounts by default (see g_unix_mount_entry_is_system_internal()), so this call can return the IOErrorEnum.NOT_SUPPORTED error. Since GLib 2.66, the x-gvfs-notrash unix mount option can be used to disable File.trash support for particular mounts, the IOErrorEnum.NOT_SUPPORTED error will be returned in that case. Since 2.82, the x-gvfs-trash unix mount option can be used to enable File.trash support for particular system mounts.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

trash_async¶

def trash_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sends file to the Trash location, if possible.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

trash_finish¶

def trash_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous file trashing operation, started with File.trash_async.

Parameters:

result — a AsyncResult

unmount_mountable¶

def unmount_mountable(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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

Unmounts a file of type G_FILE_TYPE_MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.unmount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

unmount_mountable_finish¶

def unmount_mountable_finish(self, result: AsyncResult) -> bool

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

Finishes an unmount operation, see File.unmount_mountable for details.

Finish an asynchronous unmount operation that was started with File.unmount_mountable.

Parameters:

result — a AsyncResult

unmount_mountable_with_operation¶

def unmount_mountable_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Unmounts a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.unmount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

unmount_mountable_with_operation_finish¶

def unmount_mountable_with_operation_finish(self, result: AsyncResult) -> bool

Finishes an unmount operation, see File.unmount_mountable_with_operation for details.

Finish an asynchronous unmount operation that was started with File.unmount_mountable_with_operation.

Parameters:

result — a AsyncResult

Static functions¶

new_build_filenamev¶

@staticmethod
def new_build_filenamev(args: list[str | bytes | os.PathLike[str] | os.PathLike[bytes]]) -> File

Constructs a File from a vector of elements using the correct separator for filenames.

Using this function is equivalent to calling GLib.build_filenamev, followed by File.new_for_path on the result.

Parameters:

args — None-terminated array of strings containing the path elements.

new_for_commandline_arg¶

@staticmethod
def new_for_commandline_arg(arg: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> File

Creates a File with the given argument from the command line. The value of arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if arg points to a malformed path.

Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. Application also uses UTF-8 but ApplicationCommandLine.create_file_for_arg may be more useful for you there. It is also always possible to use this function with GLib.OptionContext arguments of type GLib.OptionArg.FILENAME.

Parameters:

arg — a command line string

new_for_commandline_arg_and_cwd¶

@staticmethod
def new_for_commandline_arg_and_cwd(arg: str | bytes | os.PathLike[str] | os.PathLike[bytes], cwd: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> File

Creates a File with the given argument from the command line.

This function is similar to File.new_for_commandline_arg except that it allows for passing the current working directory as an argument instead of using the current working directory of the process.

This is useful if the commandline argument was given in a context other than the invocation of the current process.

Parameters:

arg — a command line string
cwd — the current working directory of the commandline

new_for_path¶

@staticmethod
def new_for_path(path: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> File

Constructs a File for a given path. This operation never fails, but the returned object might not support any I/O operation if path is malformed.

Parameters:

path — a string containing a relative or absolute path. The string must be encoded in the glib filename encoding.

new_for_uri¶

@staticmethod
def new_for_uri(uri: str) -> File

Constructs a File for a given URI. This operation never fails, but the returned object might not support any I/O operation if uri is malformed or if the uri type is not supported.

Parameters:

uri — a UTF-8 string containing a URI

new_tmp¶

@staticmethod
def new_tmp(tmpl: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None = ...) -> tuple[File, FileIOStream]

Opens a file in the preferred directory for temporary files (as returned by GLib.get_tmp_dir) and returns a File and FileIOStream pointing to it.

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is None, a default template is used.

Unlike the other File constructors, this will return None if a temporary file could not be created.

Parameters:

tmpl — Template for the file name, as in GLib.file_open_tmp, or None for a default template

new_tmp_async¶

@staticmethod
def new_tmp_async(tmpl: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None, io_priority: int, cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

Asynchronously opens a file in the preferred directory for temporary files (as returned by GLib.get_tmp_dir) as File.new_tmp.

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is None, a default template is used.

Parameters:

tmpl — Template for the file name, as in GLib.file_open_tmp, or None for a default template
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is done

new_tmp_dir_async¶

@staticmethod
def new_tmp_dir_async(tmpl: str | bytes | os.PathLike[str] | os.PathLike[bytes] | None, io_priority: int, cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

Asynchronously creates a directory in the preferred directory for temporary files (as returned by GLib.get_tmp_dir) as GLib.Dir.make_tmp.

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is None, a default template is used.

Parameters:

tmpl — Template for the file name, as in GLib.Dir.make_tmp, or None for a default template
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is done

new_tmp_dir_finish¶

@staticmethod
def new_tmp_dir_finish(result: AsyncResult) -> File

Finishes a temporary directory creation started by File.new_tmp_dir_async.

Parameters:

result — a AsyncResult

new_tmp_finish¶

@staticmethod
def new_tmp_finish(result: AsyncResult) -> tuple[File, FileIOStream]

Finishes a temporary file creation started by File.new_tmp_async.

Parameters:

result — a AsyncResult

parse_name¶

@staticmethod
def parse_name(parse_name: str) -> File

Constructs a File with the given parse_name (i.e. something given by File.get_parse_name). This operation never fails, but the returned object might not support any I/O operation if the parse_name cannot be parsed.

Parameters:

parse_name — a file name or path to be parsed

Virtual methods¶

do_append_to¶

def do_append_to(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Gets an output stream for appending data to the file. If the file doesn't already exist it is created.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error. If the file is a directory the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

do_append_to_async¶

def do_append_to_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for appending.

For more details, see File.append_to which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.append_to_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_append_to_finish¶

def do_append_to_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file append operation started with File.append_to_async.

Parameters:

res — AsyncResult

do_copy¶

def do_copy(self, destination: File, flags: FileCopyFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ...) -> bool

Copies the file source to the location specified by destination. Can not handle recursive copies of directories.

If the flag FileCopyFlags.OVERWRITE is specified an already existing destination file is overwritten.

If the flag FileCopyFlags.NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.

If the flag FileCopyFlags.ALL_METADATA is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see FileInfo).

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 IOErrorEnum.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 IOErrorEnum.NOT_FOUND error is returned, independent on the status of the destination.

If FileCopyFlags.OVERWRITE is not specified and the target exists, then the error IOErrorEnum.EXISTS is returned.

If trying to overwrite a file over a directory, the IOErrorEnum.IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the IOErrorEnum.WOULD_MERGE error is returned.

If the source is a directory and the target does not exist, or FileCopyFlags.OVERWRITE is specified and the target is a file, then the IOErrorEnum.WOULD_RECURSE error is returned.

If you are interested in copying the File object itself (not the on-disk file), see File.dup.

Parameters:

destination — destination File
flags — set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore
progress_callback — function to callback with progress information, or None if progress information is not needed

do_copy_async¶

def do_copy_async(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Copies the file source to the location specified by destination asynchronously. For details of the behaviour, see File.copy.

If progress_callback is not None, then that function that will be called just like in File.copy. The callback will run in the default main context of the thread calling File.copy_async — the same context as callback is run in.

When the operation is finished, callback will be called. You can then call File.copy_finish to get the result of the operation.

Parameters:

destination — destination File
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
progress_callback — function to callback with progress information, or None if progress information is not needed
callback — a GAsyncReadyCallback to call when the request is satisfied

do_copy_finish¶

def do_copy_finish(self, res: AsyncResult) -> bool

Finishes copying the file started with File.copy_async.

Parameters:

res — a AsyncResult

do_create¶

def do_create(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Creates a new file and returns an output stream for writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If a file or directory with this name already exists the IOErrorEnum.EXISTS error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is to long IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

do_create_async¶

def do_create_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.

For more details, see File.create which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.create_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_create_finish¶

def do_create_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file create operation started with File.create_async.

Parameters:

res — a AsyncResult

do_create_readwrite¶

def do_create_readwrite(self, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileIOStream

Creates a new file and returns a stream for reading and writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If a file or directory with this name already exists, the IOErrorEnum.EXISTS error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is too long, IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

do_create_readwrite_async¶

def do_create_readwrite_async(self, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.

For more details, see File.create_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.create_readwrite_finish to get the result of the operation.

Parameters:

flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_create_readwrite_finish¶

def do_create_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file create operation started with File.create_readwrite_async.

Parameters:

res — a AsyncResult

do_delete_file¶

def do_delete_file(self, cancellable: Cancellable | None = ...) -> bool

Deletes a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as GLib.unlink.

If file doesn’t exist, IOErrorEnum.NOT_FOUND will be returned. This allows for deletion to be implemented avoiding time-of-check to time-of-use races:

g_autoptr(GError) local_error = NULL;
if (!g_file_delete (my_file, my_cancellable, &local_error) &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
  {
    // deletion failed for some reason other than the file not existing:
    // so report the error
    g_warning ("Failed to delete %s: %s",
               g_file_peek_path (my_file), local_error->message);
  }

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_delete_file_async¶

def do_delete_file_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously delete a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as GLib.unlink.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_delete_file_finish¶

def do_delete_file_finish(self, result: AsyncResult) -> bool

Finishes deleting a file started with File.delete_async.

Parameters:

result — a AsyncResult

do_dup¶

def do_dup(self) -> File

Duplicates a File handle. This operation does not duplicate the actual file or directory represented by the File; see File.copy if attempting to copy a file.

File.dup is useful when a second handle is needed to the same underlying file, for use in a separate thread (File is not thread-safe). For use within the same thread, use GObject.Object.ref to increment the existing object’s reference count.

This call does no blocking I/O.

do_eject_mountable¶

def do_eject_mountable(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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

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 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_eject_mountable_finish¶

def do_eject_mountable_finish(self, result: AsyncResult) -> bool

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

Finishes an asynchronous eject operation started by File.eject_mountable.

Parameters:

result — a AsyncResult

do_eject_mountable_with_operation¶

def do_eject_mountable_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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 File.eject_mountable_with_operation_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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_eject_mountable_with_operation_finish¶

def do_eject_mountable_with_operation_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous eject operation started by File.eject_mountable_with_operation.

Parameters:

result — a AsyncResult

do_enumerate_children¶

def do_enumerate_children(self, attributes: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> FileEnumerator

Gets the requested information about the files in a directory. The result is a FileEnumerator object that will give out FileInfo objects for all the files in the directory.

The attributes 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. attributes should be a comma-separated list of attributes 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 FILE_ATTRIBUTE_STANDARD_NAME. FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call FileEnumerator.get_child or FileEnumerator.iterate on the returned enumerator.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is not a directory, the IOErrorEnum.NOT_DIRECTORY error will be returned. Other errors are possible too.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

do_enumerate_children_async¶

def do_enumerate_children_async(self, attributes: str, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about the files in a directory. The result is a FileEnumerator object that will give out FileInfo objects for all the files in the directory.

For more details, see File.enumerate_children which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.enumerate_children_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_enumerate_children_finish¶

def do_enumerate_children_finish(self, res: AsyncResult) -> FileEnumerator

Finishes an async enumerate children operation. See File.enumerate_children_async.

Parameters:

res — a AsyncResult

do_equal¶

def do_equal(self, file2: File) -> bool

Checks if the two given GFiles refer to the same file.

This function can be used with File.hash to insert Files efficiently in a hash table.

Note that two GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing. For local files, this function essentially compares the file paths, so two Files which point to different hard or soft links will not be considered equal, despite pointing to the same content.

For determining whether two files are hardlinked, see FILE_ATTRIBUTE_ID_FILE.

This call does no blocking I/O.

Parameters:

file2 — the second File

do_find_enclosing_mount¶

def do_find_enclosing_mount(self, cancellable: Cancellable | None = ...) -> Mount

Gets a Mount for the File.

Mount is returned only for user interesting locations, see VolumeMonitor. If the FileIface for file does not have a #mount, error will be set to IOErrorEnum.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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_find_enclosing_mount_async¶

def do_find_enclosing_mount_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the mount for the file.

For more details, see File.find_enclosing_mount which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.find_enclosing_mount_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_find_enclosing_mount_finish¶

def do_find_enclosing_mount_finish(self, res: AsyncResult) -> Mount

Finishes an asynchronous find mount request. See File.find_enclosing_mount_async.

Parameters:

res — a AsyncResult

do_get_basename¶

def do_get_basename(self) -> str | None

Gets the base name (the last component of the path) for a given 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 FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with File.query_info.

This call does no blocking I/O.

do_get_child_for_display_name¶

def do_get_child_for_display_name(self, display_name: str) -> File

Gets the child of file for a given display_name (i.e. a UTF-8 version of the name). If this function fails, it returns None and error will be set. This is very useful when constructing a File 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.

Parameters:

display_name — string to a possible child

do_get_parent¶

def do_get_parent(self) -> File | None

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.

do_get_parse_name¶

def do_get_parse_name(self) -> str

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 File back using File.parse_name.

This is generally used to show the 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 UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped).

This call does no blocking I/O.

do_get_path¶

def do_get_path(self) -> str | None

Gets the local pathname for File, if one exists. If non-None, this is guaranteed to be an absolute, canonical path. It might contain symlinks.

This call does no blocking I/O.

do_get_relative_path¶

def do_get_relative_path(self, descendant: File) -> str | None

Gets the path for descendant relative to parent.

This call does no blocking I/O.

Parameters:

descendant — input File

do_get_uri¶

def do_get_uri(self) -> str

Gets the URI for the file.

This call does no blocking I/O.

do_get_uri_scheme¶

def do_get_uri_scheme(self) -> str | None

Gets the URI scheme for a File. RFC 3986 decodes the scheme as:

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include "file", "http", "ftp", etc.

The scheme can be different from the one used to construct the File, in that it might be replaced with one that is logically equivalent to the File.

This call does no blocking I/O.

do_has_uri_scheme¶

def do_has_uri_scheme(self, uri_scheme: str) -> bool

Checks to see if a File has a given URI scheme.

This call does no blocking I/O.

Parameters:

uri_scheme — a string containing a URI scheme

do_hash¶

def do_hash(self) -> int

Creates a hash value for a File.

This call does no blocking I/O.

do_is_native¶

def do_is_native(self) -> bool

Checks to see if a file is native to the platform.

A native file is 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 File.get_path will still return a native path.

This call does no blocking I/O.

do_make_directory¶

def do_make_directory(self, cancellable: Cancellable | None = ...) -> bool

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 File. To recursively create directories, see File.make_directory_with_parents.

This function will fail if the parent directory does not exist, setting error to IOErrorEnum.NOT_FOUND. If the file system doesn't support creating directories, this function will fail, setting error to IOErrorEnum.NOT_SUPPORTED. If the directory already exists, IOErrorEnum.EXISTS will be returned.

For a local 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_make_directory_async¶

def do_make_directory_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a directory.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_make_directory_finish¶

def do_make_directory_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous directory creation, started with File.make_directory_async.

Parameters:

result — a AsyncResult

do_make_symbolic_link¶

def do_make_symbolic_link(self, symlink_value: str | bytes | os.PathLike[str] | os.PathLike[bytes], cancellable: Cancellable | None = ...) -> bool

Creates a symbolic link named file which contains the string symlink_value.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

symlink_value — a string with the path for the target of the new symlink
cancellable — optional Cancellable object, None to ignore

do_make_symbolic_link_async¶

def do_make_symbolic_link_async(self, symlink_value: str | bytes | os.PathLike[str] | os.PathLike[bytes], io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously creates a symbolic link named file which contains the string symlink_value.

Parameters:

symlink_value — a string with the path for the target of the new symlink
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_make_symbolic_link_finish¶

def do_make_symbolic_link_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous symbolic link creation, started with File.make_symbolic_link_async.

Parameters:

result — a AsyncResult

do_measure_disk_usage¶

def do_measure_disk_usage(self, flags: FileMeasureFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileMeasureProgressCallback | None = ...) -> tuple[bool, int, int, int]

Recursively measures the disk usage of file.

This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links).

By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless FileMeasureFlags.REPORT_ANY_ERROR is given in flags.

The returned size, disk_usage, is in bytes and should be formatted with GLib.format_size in order to get something reasonable for showing in a user interface.

progress_callback and progress_data can be given to request periodic progress updates while scanning. See the documentation for GFileMeasureProgressCallback for information about when and how the callback will be invoked.

Parameters:

flags — FileMeasureFlags
cancellable — optional Cancellable
progress_callback — a GFileMeasureProgressCallback

do_measure_disk_usage_finish¶

def do_measure_disk_usage_finish(self, result: AsyncResult) -> tuple[bool, int, int, int]

Collects the results from an earlier call to g_file_measure_disk_usage_async(). See File.measure_disk_usage for more information.

Parameters:

result — the AsyncResult passed to your GAsyncReadyCallback

do_monitor_dir¶

def do_monitor_dir(self, flags: FileMonitorFlags | int, cancellable: Cancellable | None = ...) -> FileMonitor

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 IOErrorEnum.CANCELLED will be returned.

It does not make sense for flags to contain FileMonitorFlags.WATCH_HARD_LINKS, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with File.monitor.

Parameters:

flags — a set of FileMonitorFlags
cancellable — optional Cancellable object, None to ignore

do_monitor_file¶

def do_monitor_file(self, flags: FileMonitorFlags | int, cancellable: Cancellable | None = ...) -> FileMonitor

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 IOErrorEnum.CANCELLED will be returned.

If flags contains FileMonitorFlags.WATCH_HARD_LINKS then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the FileMonitor backend and/or filesystem type.

Parameters:

flags — a set of FileMonitorFlags
cancellable — optional Cancellable object, None to ignore

do_mount_enclosing_volume¶

def do_mount_enclosing_volume(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

do_mount_enclosing_volume_finish¶

def do_mount_enclosing_volume_finish(self, result: AsyncResult) -> bool

Finishes a mount operation started by File.mount_enclosing_volume.

Parameters:

result — a AsyncResult

do_mount_mountable¶

def do_mount_mountable(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when, for instance, passwords are needed during authentication.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_mount_mountable_finish¶

def do_mount_mountable_finish(self, result: AsyncResult) -> File

Finishes a mount operation. See File.mount_mountable for details.

Finish an asynchronous mount operation that was started with File.mount_mountable.

Parameters:

result — a AsyncResult

do_move¶

def do_move(self, destination: File, flags: FileCopyFlags | int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ...) -> bool

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 FileCopyFlags.OVERWRITE is specified an already existing destination file is overwritten.

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 IOErrorEnum.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 IOErrorEnum.NOT_FOUND error is returned, independent on the status of the destination.

If FileCopyFlags.OVERWRITE is not specified and the target exists, then the error IOErrorEnum.EXISTS is returned.

If trying to overwrite a file over a directory, the IOErrorEnum.IS_DIRECTORY error is returned. If trying to overwrite a directory with a directory the IOErrorEnum.WOULD_MERGE error is returned.

If the source is a directory and the target does not exist, or FileCopyFlags.OVERWRITE is specified and the target is a file, then the IOErrorEnum.WOULD_RECURSE error may be returned (if the native move operation isn't available).

Parameters:

destination — File pointing to the destination location
flags — set of FileCopyFlags
cancellable — optional Cancellable object, None to ignore
progress_callback — GFileProgressCallback function for updates

do_move_async¶

def do_move_async(self, destination: File, flags: FileCopyFlags | int, io_priority: int, cancellable: Cancellable | None = ..., progress_callback: FileProgressCallback | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously moves a file source to the location of destination. For details of the behaviour, see File.move.

If progress_callback is not None, then that function that will be called just like in File.move. The callback will run in the default main context of the thread calling File.move_async — the same context as callback is run in.

When the operation is finished, callback will be called. You can then call File.move_finish to get the result of the operation.

Parameters:

destination — File pointing to the destination location
flags — set of FileCopyFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
progress_callback — GFileProgressCallback function for updates
callback — a GAsyncReadyCallback to call when the request is satisfied

do_move_finish¶

def do_move_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous file movement, started with File.move_async.

Parameters:

result — a AsyncResult

do_open_readwrite¶

def do_open_readwrite(self, cancellable: Cancellable | None = ...) -> FileIOStream

Opens an existing file for reading and writing. The result is a FileIOStream that can be used to read and write the contents 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is a directory, the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

cancellable — a Cancellable

do_open_readwrite_async¶

def do_open_readwrite_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for reading and writing.

For more details, see File.open_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.open_readwrite_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_open_readwrite_finish¶

def do_open_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file read operation started with File.open_readwrite_async.

Parameters:

res — a AsyncResult

do_poll_mountable¶

def do_poll_mountable(self, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Polls a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

do_poll_mountable_finish¶

def do_poll_mountable_finish(self, result: AsyncResult) -> bool

Finishes a poll operation. See File.poll_mountable for details.

Finish an asynchronous poll operation that was polled with File.poll_mountable.

Parameters:

result — a AsyncResult

do_prefix_matches¶

def do_prefix_matches(self, file: File) -> bool

Checks whether file has the prefix specified by prefix.

In other words, if the names of initial elements of file's 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.

A File is not a prefix of itself. If you want to check for equality, use File.equal.

This call does no 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.

Parameters:

file — input File

do_query_exists¶

def do_query_exists(self, cancellable: Cancellable | None = ...) -> bool

Utility function to check if a particular file exists.

The fallback implementation of this API is using File.query_info and therefore may do blocking I/O. To asynchronously query the existence of a file, use File.query_info_async.

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 File.create which will either atomically create the file or fail with a IOErrorEnum.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 an 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.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_query_filesystem_info¶

def do_query_filesystem_info(self, attributes: str, cancellable: Cancellable | None = ...) -> FileInfo

Similar to 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 attributes value is a string that specifies the 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. attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

attributes — an attribute query string
cancellable — optional Cancellable object, None to ignore

do_query_filesystem_info_async¶

def do_query_filesystem_info_async(self, attributes: str, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about the filesystem that the specified file is on. The result is a FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see File.query_filesystem_info which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.query_info_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_query_filesystem_info_finish¶

def do_query_filesystem_info_finish(self, res: AsyncResult) -> FileInfo

Finishes an asynchronous filesystem info query. See File.query_filesystem_info_async.

Parameters:

res — a AsyncResult

do_query_info¶

def do_query_info(self, attributes: str, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> FileInfo

Gets the requested information about specified file.

The result is a FileInfo object that contains key-value attributes (such as the type or size of the file).

The attributes 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. In particular this means that if a file is inaccessible (due to being in a folder with restrictive permissions), for example, you can expect the returned FileInfo to have very few attributes set. You should check whether an attribute is set using FileInfo.has_attribute before trying to retrieve its value.

It is guaranteed that if any of the following attributes are listed in attributes, they will always be set in the returned FileInfo, even if the user doesn’t have permissions to access the file:

attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "\*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query might be "standard::*,owner::user". The standard attributes are available as defines, like FILE_ATTRIBUTE_STANDARD_NAME.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass FileQueryInfoFlags.NOFOLLOW_SYMLINKS in flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of file system the file is on.

Parameters:

attributes — an attribute query string
flags — flags to affect the query operation
cancellable — optional cancellable object

do_query_info_async¶

def do_query_info_async(self, attributes: str, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously gets the requested information about specified file. The result is a FileInfo object that contains key-value attributes (such as type or size for the file).

For more details, see File.query_info which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.query_info_finish to get the result of the operation.

Parameters:

attributes — an attribute query string
flags — a set of FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_query_info_finish¶

def do_query_info_finish(self, res: AsyncResult) -> FileInfo

Finishes an asynchronous file info query. See File.query_info_async.

Parameters:

res — a AsyncResult

do_query_settable_attributes¶

def do_query_settable_attributes(self, cancellable: Cancellable | None = ...) -> FileAttributeInfoList

Obtain the list of settable attributes for the file.

Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_query_writable_namespaces¶

def do_query_writable_namespaces(self, cancellable: Cancellable | None = ...) -> FileAttributeInfoList

Obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace).

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_read_async¶

def do_read_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously opens file for reading.

For more details, see File.read which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.read_finish to get the result of the operation.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_read_finish¶

def do_read_finish(self, res: AsyncResult) -> FileInputStream

Finishes an asynchronous file read operation started with File.read_async.

Parameters:

res — a AsyncResult

do_read_fn¶

def do_read_fn(self, cancellable: Cancellable | None = ...) -> FileInputStream

Opens a file for reading. The result is a FileInputStream that can be used to read the contents 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 IOErrorEnum.CANCELLED will be returned.

If the file does not exist, the IOErrorEnum.NOT_FOUND error will be returned. If the file is a directory, the IOErrorEnum.IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

cancellable — a Cancellable

do_replace¶

def do_replace(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileOutputStream

Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed.

By default files created are generally readable by everyone, but if you pass FileCreateFlags.PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target 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 IOErrorEnum.CANCELLED will be returned.

If you pass in a non-None etag value and file already exists, then this value is compared to the current entity tag of the file, and if they differ an IOErrorEnum.WRONG_ETAG error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from FileOutputStream.get_etag after you've finished writing and closed the FileOutputStream. When you load a new file you can use FileInputStream.query_info to get the etag of the file.

If make_backup is True, this function will attempt to make a backup of the current file before overwriting it. If this fails a IOErrorEnum.CANT_CREATE_BACKUP error will be returned. If you want to replace anyway, try again with make_backup set to False.

If the file is a directory the IOErrorEnum.IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a IOErrorEnum.NOT_REGULAR_FILE error will be returned. Some file systems don't allow all file names, and may return an IOErrorEnum.INVALID_FILENAME error, and if the name is to long IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Parameters:

etag — an optional entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

do_replace_async¶

def do_replace_async(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.

For more details, see File.replace which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.replace_finish to get the result of the operation.

Parameters:

etag — an entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_replace_finish¶

def do_replace_finish(self, res: AsyncResult) -> FileOutputStream

Finishes an asynchronous file replace operation started with File.replace_async.

Parameters:

res — a AsyncResult

do_replace_readwrite¶

def do_replace_readwrite(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, cancellable: Cancellable | None = ...) -> FileIOStream

Returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

For details about the behaviour, see File.replace which does the same thing but returns an output stream only.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Parameters:

etag — an optional entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
cancellable — optional Cancellable object, None to ignore

do_replace_readwrite_async¶

def do_replace_readwrite_async(self, etag: str | None, make_backup: bool, flags: FileCreateFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first.

For more details, see File.replace_readwrite which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.replace_readwrite_finish to get the result of the operation.

Parameters:

etag — an entity tag for the current File, or None to ignore
make_backup — True if a backup should be created
flags — a set of FileCreateFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_replace_readwrite_finish¶

def do_replace_readwrite_finish(self, res: AsyncResult) -> FileIOStream

Finishes an asynchronous file replace operation started with File.replace_readwrite_async.

Parameters:

res — a AsyncResult

do_resolve_relative_path¶

def do_resolve_relative_path(self, relative_path: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> File

Resolves a relative path for file to an absolute path.

This call does no blocking I/O.

If the relative_path is an absolute path name, the resolution is done absolutely (without taking file path as base).

Parameters:

relative_path — a given relative path string

do_set_attribute¶

def do_set_attribute(self, attribute: str, type: FileAttributeType | int, value_p: int | None, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Sets an attribute in the file with attribute name attribute to value_p.

Some attributes can be unset by setting type to FileAttributeType.INVALID and value_p to None.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

attribute — a string containing the attribute's name
type — The type of the attribute
value_p — a pointer to the value (or the pointer itself if the type is a pointer type)
flags — a set of FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

do_set_attributes_async¶

def do_set_attributes_async(self, info: FileInfo, flags: FileQueryInfoFlags | int, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sets the attributes of file with info.

For more details, see File.set_attributes_from_info, which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.set_attributes_finish to get the result of the operation.

Parameters:

info — a FileInfo
flags — a FileQueryInfoFlags
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_set_attributes_finish¶

def do_set_attributes_finish(self, result: AsyncResult) -> tuple[bool, FileInfo]

Finishes setting an attribute started in File.set_attributes_async.

Parameters:

result — a AsyncResult

do_set_attributes_from_info¶

def do_set_attributes_from_info(self, info: FileInfo, flags: FileQueryInfoFlags | int, cancellable: Cancellable | None = ...) -> bool

Tries to set all attributes in the FileInfo on the target values, not stopping on the first error.

If there is any error during this operation then error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to FileAttributeStatus.ERROR_SETTING, which means you can also detect further errors.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

info — a FileInfo
flags — FileQueryInfoFlags
cancellable — optional Cancellable object, None to ignore

do_set_display_name¶

def do_set_display_name(self, display_name: str, cancellable: Cancellable | None = ...) -> File

Renames file to the specified display name.

The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the file is renamed to this.

If you want to implement a rename operation in the user interface the edit name (FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to File.set_display_name.

On success the resulting converted filename is 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 IOErrorEnum.CANCELLED will be returned.

Parameters:

display_name — a string
cancellable — optional Cancellable object, None to ignore

do_set_display_name_async¶

def do_set_display_name_async(self, display_name: str, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sets the display name for a given File.

For more details, see File.set_display_name which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call File.set_display_name_finish to get the result of the operation.

Parameters:

display_name — a string
io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_set_display_name_finish¶

def do_set_display_name_finish(self, res: AsyncResult) -> File

Finishes setting a display name started with File.set_display_name_async.

Parameters:

res — a AsyncResult

do_start_mountable¶

def do_start_mountable(self, flags: DriveStartFlags | int, start_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Starts a file of type FileType.MOUNTABLE. Using start_operation, you can request callbacks when, for instance, passwords are needed during authentication.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.mount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
start_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

do_start_mountable_finish¶

def do_start_mountable_finish(self, result: AsyncResult) -> bool

Finishes a start operation. See File.start_mountable for details.

Finish an asynchronous start operation that was started with File.start_mountable.

Parameters:

result — a AsyncResult

do_stop_mountable¶

def do_stop_mountable(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Stops a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.stop_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction.
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied, or None

do_stop_mountable_finish¶

def do_stop_mountable_finish(self, result: AsyncResult) -> bool

Finishes a stop operation, see File.stop_mountable for details.

Finish an asynchronous stop operation that was started with File.stop_mountable.

Parameters:

result — a AsyncResult

do_trash¶

def do_trash(self, cancellable: Cancellable | None = ...) -> bool

Sends file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Trashing is disabled for system mounts by default (see g_unix_mount_entry_is_system_internal()), so this call can return the IOErrorEnum.NOT_SUPPORTED error. Since GLib 2.66, the x-gvfs-notrash unix mount option can be used to disable File.trash support for particular mounts, the IOErrorEnum.NOT_SUPPORTED error will be returned in that case. Since 2.82, the x-gvfs-trash unix mount option can be used to enable File.trash support for particular system mounts.

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 IOErrorEnum.CANCELLED will be returned.

Parameters:

cancellable — optional Cancellable object, None to ignore

do_trash_async¶

def do_trash_async(self, io_priority: int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Asynchronously sends file to the Trash location, if possible.

Parameters:

io_priority — the I/O priority of the request
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_trash_finish¶

def do_trash_finish(self, result: AsyncResult) -> bool

Finishes an asynchronous file trashing operation, started with File.trash_async.

Parameters:

result — a AsyncResult

do_unmount_mountable¶

def do_unmount_mountable(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

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

Unmounts a file of type G_FILE_TYPE_MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.unmount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_unmount_mountable_finish¶

def do_unmount_mountable_finish(self, result: AsyncResult) -> bool

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

Finishes an unmount operation, see File.unmount_mountable for details.

Finish an asynchronous unmount operation that was started with File.unmount_mountable.

Parameters:

result — a AsyncResult

do_unmount_mountable_with_operation¶

def do_unmount_mountable_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[File | None, AsyncResult], None] | None = ...) -> None

Unmounts a file of type FileType.MOUNTABLE.

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 IOErrorEnum.CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call File.unmount_mountable_finish to get the result of the operation.

Parameters:

flags — flags affecting the operation
mount_operation — a MountOperation, or None to avoid user interaction
cancellable — optional Cancellable object, None to ignore
callback — a GAsyncReadyCallback to call when the request is satisfied

do_unmount_mountable_with_operation_finish¶

def do_unmount_mountable_with_operation_finish(self, result: AsyncResult) -> bool

Finishes an unmount operation, see File.unmount_mountable_with_operation for details.

Finish an asynchronous unmount operation that was started with File.unmount_mountable_with_operation.

Parameters:

result — a AsyncResult