File#
- class File(*args, **kwargs)#
GFile
is a high level abstraction for manipulating files on a
virtual file system. GFile
’s 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:
new_for_path
if you have a path.new_for_uri
if you have a URI.new_for_commandline_arg
ornew_for_commandline_arg_and_cwd
for a command line argument.new_tmp
to create a temporary file from a template.new_tmp_async
to asynchronously create a temporary file.new_tmp_dir_async
to asynchronously create a temporary directory.parse_name
from a UTF-8 string gotten fromget_parse_name
.new_build_filename
ornew_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
GFile
’s are extensible it could also be something else that corresponds
to a pathname in a userspace implementation of a filesystem.
GFile
’s 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 get_parent
to get an identifier for the
parent directory, get_child
to get a child within a
directory, and resolve_relative_path
to resolve a relative
path between two GFile
’s. There can be multiple hierarchies, so you may not
end up at the same root if you repeatedly call get_parent
on two different files.
All GFile
’s have a basename (get with 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
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 GFile
’s 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 GFile
’s 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 GFile
’s.
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 Gio.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:
mount_mountable
to mount a mountable file.unmount_mountable_with_operation
to unmount a mountable file.eject_mountable_with_operation
to eject a mountable file.
Methods#
- class File
- append_to(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Some file systems don’t allow all file names, and may return an
INVALID_FILENAME
error. If the file is a directory theIS_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(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for appending.For more details, see
append_to()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callappend_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- append_to_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file append operation started with
append_to_async()
.- Parameters:
res –
AsyncResult
- create(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If a file or directory with this name already exists the
EXISTS
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is to longFILENAME_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(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
create()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callcreate_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- create_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file create operation started with
create_async()
.- Parameters:
res – a
AsyncResult
- create_readwrite(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If a file or directory with this name already exists, the
EXISTS
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is too long,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.
Added in version 2.22.
- Parameters:
flags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- create_readwrite_async(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
create_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callcreate_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- create_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file create operation started with
create_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- delete(cancellable: Cancellable | None = 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 asunlink()
.If
file
doesn’t exist,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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- delete_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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 asunlink()
.Added in version 2.34.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- delete_finish(result: AsyncResult) bool #
Finishes deleting a file started with
delete_async()
.Added in version 2.34.
- Parameters:
result – a
AsyncResult
- dup() File #
Duplicates a
File
handle. This operation does not duplicate the actual file or directory represented by theFile
; seecopy()
if attempting to copy a 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, useref()
to increment the existing object’s reference count.This call does no blocking I/O.
- eject_mountable(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous eject on a mountable. When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized witheject_mountable_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Deprecated since version 2.22: Use
eject_mountable_with_operation()
instead.- Parameters:
flags – flags affecting the operation
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- eject_mountable_finish(result: AsyncResult) bool #
Finishes an asynchronous eject operation started by
eject_mountable()
.Deprecated since version 2.22: Use
eject_mountable_with_operation_finish()
instead.- Parameters:
result – a
AsyncResult
- eject_mountable_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous eject on a mountable. When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized witheject_mountable_with_operation_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- eject_mountable_with_operation_finish(result: AsyncResult) bool #
Finishes an asynchronous eject operation started by
eject_mountable_with_operation()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- enumerate_children(attributes: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) FileEnumerator #
Gets the requested information about the files in a directory. The result is a
FileEnumerator
object that will give outFileInfo
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, likeFILE_ATTRIBUTE_STANDARD_NAME
.FILE_ATTRIBUTE_STANDARD_NAME
should always be specified if you plan to callget_child()
oriterate()
on the returned enumerator.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
NOT_FOUND
error will be returned. If the file is not a directory, theNOT_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(attributes: str, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about the files in a directory. The result is a
FileEnumerator
object that will give outFileInfo
objects for all the files in the directory.For more details, see
enumerate_children()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callenumerate_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- enumerate_children_finish(res: AsyncResult) FileEnumerator #
Finishes an async enumerate children operation. See
enumerate_children_async()
.- Parameters:
res – a
AsyncResult
- equal(file2: File) bool #
Checks if the two given
File
refer to the same file.Note that two
File
that differ can still refer to the same file on the filesystem due to various forms of filename aliasing.This call does no blocking I/O.
- Parameters:
file2 – the second
File
- find_enclosing_mount(cancellable: Cancellable | None = None) Mount #
-
Mount
is returned only for user interesting locations, seeVolumeMonitor
. If theGFileIface
forfile
does not have amount
,error
will be set toNOT_FOUND
andNone
will
be returned.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- find_enclosing_mount_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the mount for the file.
For more details, see
find_enclosing_mount()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callfind_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- find_enclosing_mount_finish(res: AsyncResult) Mount #
Finishes an asynchronous find mount request. See
find_enclosing_mount_async()
.- Parameters:
res – a
AsyncResult
- get_basename() 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 withquery_info()
.This call does no blocking I/O.
- get_child(name: str) File #
Gets a child of
file
with basename equal toname
.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(display_name: str) File #
Gets the child of
file
for a givendisplay_name
(i.e. a UTF-8 version of the name). If this function fails, it returnsNone
anderror
will be set. This is very useful when constructing aFile
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() File | None #
Gets the parent directory for the
file
. If thefile
represents the root directory of the file system, thenNone
will be returned.This call does no blocking I/O.
- get_parse_name() 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 theFile
back usingparse_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() 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(descendant: File) str | None #
Gets the path for
descendant
relative toparent
.This call does no blocking I/O.
- Parameters:
descendant – input
File
- get_uri_scheme() 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 theFile
.This call does no blocking I/O.
- has_parent(parent: File | None = None) bool #
Checks if
file
has a parent, and optionally, if it isparent
.If
parent
isNone
then this function returnsTrue
iffile
has any parent at all. Ifparent
is non-None
thenTrue
is only returned iffile
is an immediate child ofparent
.Added in version 2.24.
- Parameters:
parent – the parent to check for, or
None
- has_prefix(prefix: File) bool #
Checks whether
file
has the prefix specified byprefix
.In other words, if the names of initial elements of
file
’s pathname matchprefix
. 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, useequal()
.This call does no I/O, as it works purely on names. As such it can sometimes return
False
even iffile
is inside aprefix
(from a filesystem point of view), because the prefix offile
is an alias ofprefix
.- Parameters:
prefix – input
File
- has_uri_scheme(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
- is_native() 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
, butget_path()
will still return a native path.This call does no blocking I/O.
- load_bytes(cancellable: Cancellable | None = None) tuple[Bytes, str] #
Loads the contents of
file
and returns it asBytes
.If
file
is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to callingload_contents()
andnew_take()
.For resources,
etag_out
will be set toNone
.The data contained in the resulting
Bytes
is always zero-terminated, but this is not included in theBytes
length. The resultingBytes
should be freed withunref()
when no longer in use.Added in version 2.56.
- Parameters:
cancellable – a
Cancellable
orNone
- load_bytes_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously loads the contents of
file
asBytes
.If
file
is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to callingload_contents_async()
andnew_take()
.callback
should callload_bytes_finish()
to get the result of this asynchronous operation.See
load_bytes()
for more information.Added in version 2.56.
- Parameters:
cancellable – a
Cancellable
orNone
callback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- load_bytes_finish(result: AsyncResult) tuple[Bytes, str] #
Completes an asynchronous request to
load_bytes_async()
.For resources,
etag_out
will be set toNone
.The data contained in the resulting
Bytes
is always zero-terminated, but this is not included in theBytes
length. The resultingBytes
should be freed withunref()
when no longer in use.See
load_bytes()
for more information.Added in version 2.56.
- Parameters:
result – a
AsyncResult
provided to the callback
- load_contents(cancellable: Cancellable | None = None) tuple[bool, bytes, 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 returnedcontents
should be freed withfree()
when no longer needed.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- load_contents_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous load of the
file
’s contents.For more details, see
load_contents()
which is the synchronous version of this call.When the load operation has completed,
callback
will be called withuser
data. To finish the operation, callload_contents_finish()
with theAsyncResult
returned by thecallback
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- load_contents_finish(res: AsyncResult) tuple[bool, bytes, str] #
Finishes an asynchronous load of the
file
’s contents. The contents are placed incontents
, andlength
is set to the size of thecontents
string. Thecontents
should be freed withfree()
when no longer needed. Ifetag_out
is present, it will be set to the new entity tag for thefile
.- Parameters:
res – a
AsyncResult
- load_partial_contents_finish(res: AsyncResult) tuple[bool, bytes, str] #
Finishes an asynchronous partial load operation that was started with
load_partial_contents_async()
. The data is always zero-terminated, but this is not included in the resultantlength
. The returnedcontents
should be freed withfree()
when no longer needed.- Parameters:
res – a
AsyncResult
- make_directory(cancellable: Cancellable | None = 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, seemake_directory_with_parents()
. This function will fail if the parent directory does not exist, settingerror
toNOT_FOUND
. If the file system doesn’t support creating directories, this function will fail, settingerror
toNOT_SUPPORTED
.For a local
File
the newly created directory will have the default (current) ownership and permissions of the current process.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- make_directory_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously creates a directory.
Added in version 2.38.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- make_directory_finish(result: AsyncResult) bool #
Finishes an asynchronous directory creation, started with
make_directory_async()
.Added in version 2.38.
- Parameters:
result – a
AsyncResult
- make_directory_with_parents(cancellable: Cancellable | None = 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
toNOT_SUPPORTED
. If the directory itself already exists, this function will fail settingerror
toEXISTS
, unlike the similarmkdir_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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Added in version 2.18.
- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- make_symbolic_link(symlink_value: str, cancellable: Cancellable | None = None) bool #
Creates a symbolic link named
file
which contains the stringsymlink_value
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(symlink_value: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously creates a symbolic link named
file
which contains the stringsymlink_value
.Added in version 2.74.
- 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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- make_symbolic_link_finish(result: AsyncResult) bool #
Finishes an asynchronous symbolic link creation, started with
make_symbolic_link_async()
.Added in version 2.74.
- Parameters:
result – a
AsyncResult
- measure_disk_usage(flags: FileMeasureFlags, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, *progress_data: Any) 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
REPORT_ANY_ERROR
is given inflags
.The returned size,
disk_usage
, is in bytes and should be formatted withformat_size()
in order to get something reasonable for showing in a user interface.progress_callback
andprogress_data
can be given to request periodic progress updates while scanning. See the documentation forFileMeasureProgressCallback
for information about when and how the callback will be invoked.Added in version 2.38.
- Parameters:
flags –
FileMeasureFlags
cancellable – optional
Cancellable
progress_callback – a
FileMeasureProgressCallback
progress_data – user_data for
progress_callback
- measure_disk_usage_finish(result: AsyncResult) tuple[bool, int, int, int] #
Collects the results from an earlier call to
measure_disk_usage_async()
. Seemeasure_disk_usage()
for more information.Added in version 2.38.
- Parameters:
result – the
AsyncResult
passed to yourAsyncReadyCallback
- monitor(flags: FileMonitorFlags, cancellable: Cancellable | None = None) FileMonitor #
Obtains a file or directory monitor for the given file, depending on the type of the file.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Added in version 2.18.
- Parameters:
flags – a set of
FileMonitorFlags
cancellable – optional
Cancellable
object,None
to ignore
- monitor_directory(flags: FileMonitorFlags, cancellable: Cancellable | None = None) FileMonitor #
Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.It does not make sense for
flags
to containWATCH_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 withmonitor()
.- Parameters:
flags – a set of
FileMonitorFlags
cancellable – optional
Cancellable
object,None
to ignore
- monitor_file(flags: FileMonitorFlags, cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
flags
containsWATCH_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 infile
to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on theFileMonitor
backend and/or filesystem type.- Parameters:
flags – a set of
FileMonitorFlags
cancellable – optional
Cancellable
object,None
to ignore
- mount_enclosing_volume(flags: MountMountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts a
mount_operation
, mounting the volume that contains the filelocation
.When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized withmount_enclosing_volume_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- mount_enclosing_volume_finish(result: AsyncResult) bool #
Finishes a mount operation started by
mount_enclosing_volume()
.- Parameters:
result – a
AsyncResult
- mount_mountable(flags: MountMountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- mount_mountable_finish(result: AsyncResult) File #
Finishes a mount operation. See
mount_mountable()
for details.Finish an asynchronous mount operation that was started with
mount_mountable()
.- Parameters:
result – a
AsyncResult
- move(destination: File, flags: FileCopyFlags, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, *progress_callback_data: Any) bool #
Tries to move the file or directory
source
to the location specified bydestination
. 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
OVERWRITE
is specified an already existingdestination
file is overwritten.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
progress_callback
is notNone
, then the operation can be monitored by setting this to aFileProgressCallback
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 theNOT_FOUND
error is returned, independent on the status of thedestination
.If
OVERWRITE
is not specified and the target exists, then the errorEXISTS
is returned.If trying to overwrite a file over a directory, the
IS_DIRECTORY
error is returned. If trying to overwrite a directory with a directory theWOULD_MERGE
error is returned.If the source is a directory and the target does not exist, or
OVERWRITE
is specified and the target is a file, then theWOULD_RECURSE
error may be returned (if the native move operation isn’t available).- Parameters:
destination –
File
pointing to the destination locationflags – set of
FileCopyFlags
cancellable – optional
Cancellable
object,None
to ignoreprogress_callback –
FileProgressCallback
function for updatesprogress_callback_data – gpointer to user data for the callback function
- move_async(destination: File, flags: FileCopyFlags, io_priority: int, cancellable: Cancellable | None, progress_callback_closure: Callable[[...], Any] | None, ready_callback_closure: Callable[[...], Any]) None #
Asynchronously moves a file
source
to the location ofdestination
. For details of the behaviour, seemove()
.If
progress_callback
is notNone
, then that function that will be called just like inmove()
. The callback will run in the default main context of the thread callingmove_async()
— the same context ascallback
is run in.When the operation is finished,
callback
will be called. You can then callmove_finish()
to get the result of the operation.Added in version 2.72.
- Parameters:
destination –
File
pointing to the destination locationflags – set of
FileCopyFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignoreprogress_callback_closure
ready_callback_closure
- move_finish(result: AsyncResult) bool #
Finishes an asynchronous file movement, started with
move_async()
.Added in version 2.72.
- Parameters:
result – a
AsyncResult
- new_build_filenamev(args: Sequence[str]) File #
Constructs a
File
from a vector of elements using the correct separator for filenames.Using this function is equivalent to calling
build_filenamev()
, followed bynew_for_path()
on the result.Added in version 2.78.
- Parameters:
args –
None
-terminated array of strings containing the path elements.
- new_for_commandline_arg(arg: str) File #
Creates a
File
with the given argument from the command line. The value ofarg
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 ifarg
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 butcreate_file_for_arg()
may be more useful for you there. It is also always possible to use this function withOptionContext
arguments of type%G_OPTION_ARG_FILENAME
.- Parameters:
arg – a command line string
- new_for_commandline_arg_and_cwd(arg: str, cwd: str) File #
Creates a
File
with the given argument from the command line.This function is similar to
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.
See also
create_file_for_arg()
.Added in version 2.36.
- Parameters:
arg – a command line string
cwd – the current working directory of the commandline
- new_for_path(path: str) File #
Constructs a
File
for a given path. This operation never fails, but the returned object might not support any I/O operation ifpath
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(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 ifuri
is malformed or if the uri type is not supported.- Parameters:
uri – a UTF-8 string containing a URI
- new_tmp(tmpl: str | None = None) tuple[File, FileIOStream] #
Opens a file in the preferred directory for temporary files (as returned by
get_tmp_dir()
) and returns aFile
andFileIOStream
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 isNone
, a default template is used.Unlike the other
File
constructors, this will returnNone
if a temporary file could not be created.Added in version 2.32.
- Parameters:
tmpl – Template for the file name, as in
file_open_tmp()
, orNone
for a default template
- new_tmp_async(tmpl: str | None, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
- Asynchronously opens a file in the preferred directory for temporary files
(as returned by
get_tmp_dir()
) asnew_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 isNone
, a default template is used.Added in version 2.74.
- Parameters:
tmpl – Template for the file name, as in
file_open_tmp()
, orNone
for a default templateio_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is doneuser_data – data to pass to
callback
- new_tmp_dir_async(tmpl: str | None, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously creates a directory in the preferred directory for temporary files (as returned by
get_tmp_dir()
) asmake_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 isNone
, a default template is used.Added in version 2.74.
- Parameters:
tmpl – Template for the file name, as in
make_tmp()
, orNone
for a default templateio_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is doneuser_data – data to pass to
callback
- new_tmp_dir_finish(result: AsyncResult) File #
Finishes a temporary directory creation started by
new_tmp_dir_async()
.Added in version 2.74.
- Parameters:
result – a
AsyncResult
- new_tmp_finish(result: AsyncResult) tuple[File, FileIOStream] #
Finishes a temporary file creation started by
new_tmp_async()
.Added in version 2.74.
- Parameters:
result – a
AsyncResult
- open_readwrite(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
NOT_FOUND
error will be returned. If the file is a directory, theIS_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.Added in version 2.22.
- Parameters:
cancellable – a
Cancellable
- open_readwrite_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for reading and writing.For more details, see
open_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callopen_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- open_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file read operation started with
open_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- parse_name(parse_name: str) File #
Constructs a
File
with the givenparse_name
(i.e. something given byget_parse_name()
). This operation never fails, but the returned object might not support any I/O operation if theparse_name
cannot be parsed.- Parameters:
parse_name – a file name or path to be parsed
- peek_path() str | None #
Exactly like
get_path()
, but caches the result viaset_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.
Added in version 2.56.
- poll_mountable(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Polls a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- poll_mountable_finish(result: AsyncResult) bool #
Finishes a poll operation. See
poll_mountable()
for details.Finish an asynchronous poll operation that was polled with
poll_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- query_default_handler(cancellable: Cancellable | None = None) AppInfo #
Returns the
AppInfo
that is registered as the default application to handle the file specified byfile
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- query_default_handler_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Async version of
query_default_handler()
.Added in version 2.60.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is doneuser_data – data to pass to
callback
- query_default_handler_finish(result: AsyncResult) AppInfo #
Finishes a
query_default_handler_async()
operation.Added in version 2.60.
- Parameters:
result – a
AsyncResult
- query_exists(cancellable: Cancellable | None = None) bool #
Utility function to check if a particular file exists. This is implemented using
query_info()
and as such does blocking I/O.Note that in many cases it is racy to first check for file existence and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come.
As an example of race-free checking, take the case of reading a file, and if it doesn’t exist, creating it. There are two racy versions: read it, and on error create it; and: check if it exists, if not create it. These can both result in two processes creating the file (with perhaps a partially written file as the result). The correct approach is to always try to create the file with
create()
which will either atomically create the file or fail with aEXISTS
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(flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) FileType #
Utility function to inspect the
FileType
of a file. This is implemented usingquery_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.
Added in version 2.18.
- Parameters:
flags – a set of
FileQueryInfoFlags
passed toquery_info()
cancellable – optional
Cancellable
object,None
to ignore
- query_filesystem_info(attributes: str, cancellable: Cancellable | None = None) FileInfo #
Similar to
query_info()
, but obtains information about the filesystem thefile
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 areFILE_ATTRIBUTE_FILESYSTEM_SIZE
(the total size of the filesystem in bytes),FILE_ATTRIBUTE_FILESYSTEM_FREE
(number of bytes available), andFILE_ATTRIBUTE_FILESYSTEM_TYPE
(type of the filesystem).If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
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(attributes: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about the filesystem that the specified
file
is on. The result is aFileInfo
object that contains key-value attributes (such as type or size for the file).For more details, see
query_filesystem_info()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callquery_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- query_filesystem_info_finish(res: AsyncResult) FileInfo #
Finishes an asynchronous filesystem info query. See
query_filesystem_info_async()
.- Parameters:
res – a
AsyncResult
- query_info(attributes: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) FileInfo #
Gets the requested information about specified
file
. The result is aFileInfo
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.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, likeFILE_ATTRIBUTE_STANDARD_NAME
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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
NOFOLLOW_SYMLINKS
inflags
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
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
flags – a set of
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- query_info_async(attributes: str, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about specified
file
. The result is aFileInfo
object that contains key-value attributes (such as type or size for the file).For more details, see
query_info()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callquery_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- query_info_finish(res: AsyncResult) FileInfo #
Finishes an asynchronous file info query. See
query_info_async()
.- Parameters:
res – a
AsyncResult
- query_settable_attributes(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- query_writable_namespaces(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- read(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
NOT_FOUND
error will be returned. If the file is a directory, theIS_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(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for reading.For more details, see
read()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callread_finish()
to get the result of the operation.- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- read_finish(res: AsyncResult) FileInputStream #
Finishes an asynchronous file read operation started with
read_async()
.- Parameters:
res – a
AsyncResult
- replace(etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If you pass in a non-
None
etag
value andfile
already exists, then this value is compared to the current entity tag of the file, and if they differ anWRONG_ETAG
error is returned. This generally means that the file has been changed since you last read it. You can get the new etag fromget_etag()
after you’ve finished writing and closed theFileOutputStream
. When you load a new file you can usequery_info()
to get the etag of the file.If
make_backup
isTrue
, this function will attempt to make a backup of the current file before overwriting it. If this fails aCANT_CREATE_BACKUP
error will be returned. If you want to replace anyway, try again withmake_backup
set toFalse
.If the file is a directory the
IS_DIRECTORY
error will be returned, and if the file is some other form of non-regular file then aNOT_REGULAR_FILE
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is to longFILENAME_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 <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- replace_async(etag: str | None, make_backup: bool, flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.
For more details, see
replace()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callreplace_finish()
to get the result of the operation.- Parameters:
etag – an
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- replace_contents(contents: Sequence[int], etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = None) tuple[bool, str] #
Replaces the contents of
file
withcontents
oflength
bytes.If
etag
is specified (notNone
), any existing file must have that etag, or the errorWRONG_ETAG
will be returned.If
make_backup
isTrue
, this function will attempt to make a backup offile
. Internally, it usesreplace()
, 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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 <``entity`
-tags>`_ for the document, orNone
make_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- replace_contents_async(contents: Sequence[int], etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous replacement of
file
with the givencontents
oflength
bytes.etag
will replace the document’s current entity tag.When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized withreplace_contents_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
make_backup
isTrue
, this function will attempt to make a backup offile
.Note that no copy of
contents
will be made, so it must stay valid untilcallback
is called. Seereplace_contents_bytes_async()
for aBytes
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 <``entity`
-tags>`_ for thefile
, orNone
make_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- replace_contents_bytes_async(contents: Bytes, etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Same as
replace_contents_async()
but takes aBytes
input instead. This function will keep a ref oncontents
until the operation is done. Unlikereplace_contents_async()
this allows forgetting about the content without waiting for the callback.When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized withreplace_contents_finish()
.Added in version 2.40.
- Parameters:
contents – a
Bytes
etag – a new
entity tag <``entity`
-tags>`_ for thefile
, orNone
make_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- replace_contents_finish(res: AsyncResult) tuple[bool, str] #
Finishes an asynchronous replace of the given
file
. Seereplace_contents_async()
. Setsnew_etag
to the new entity tag for the document, if present.- Parameters:
res – a
AsyncResult
- replace_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file replace operation started with
replace_async()
.- Parameters:
res – a
AsyncResult
- replace_readwrite(etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = 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
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.
Added in version 2.22.
- Parameters:
etag – an optional
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- replace_readwrite_async(etag: str | None, make_backup: bool, flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
replace_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callreplace_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
etag – an
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- replace_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file replace operation started with
replace_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- resolve_relative_path(relative_path: str) 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 takingfile
path as base).- Parameters:
relative_path – a given relative path string
- set_attribute(attribute: str, type: FileAttributeType, value_p: None, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets an attribute in the file with attribute name
attribute
tovalue_p
.Some attributes can be unset by setting
type
toINVALID
andvalue_p
toNone
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(attribute: str, value: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeBYTE_STRING
tovalue
. Ifattribute
is of a different type, this operation will fail, returningFalse
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(attribute: str, value: int, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeINT32
tovalue
. Ifattribute
is of a different type, this operation will fail.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
attribute – a string containing the attribute’s name
value – a
int
containing the attribute’s new valueflags – a
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- set_attribute_int64(attribute: str, value: int, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeINT64
tovalue
. Ifattribute
is of a different type, this operation will fail.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
attribute – a string containing the attribute’s name
value – a
guint64
containing the attribute’s new valueflags – a
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- set_attribute_string(attribute: str, value: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeSTRING
tovalue
. Ifattribute
is of a different type, this operation will fail.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(attribute: str, value: int, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeUINT32
tovalue
. Ifattribute
is of a different type, this operation will fail.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
attribute – a string containing the attribute’s name
value – a
guint32
containing the attribute’s new valueflags – a
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- set_attribute_uint64(attribute: str, value: int, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets
attribute
of typeUINT64
tovalue
. Ifattribute
is of a different type, this operation will fail.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
attribute – a string containing the attribute’s name
value – a
guint64
containing the attribute’s new valueflags – a
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- set_attributes_async(info: FileInfo, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sets the attributes of
file
withinfo
.For more details, see
set_attributes_from_info()
, which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callset_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- set_attributes_finish(result: AsyncResult) tuple[bool, FileInfo] #
Finishes setting an attribute started in
set_attributes_async()
.- Parameters:
result – a
AsyncResult
- set_attributes_from_info(info: FileInfo, flags: FileQueryInfoFlags, cancellable: Cancellable | None = 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 toERROR_SETTING
, which means you can also detect further errors.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
info – a
FileInfo
flags –
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- set_display_name(display_name: str, cancellable: Cancellable | None = 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 toset_display_name()
.On success the resulting converted filename is returned.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
display_name – a string
cancellable – optional
Cancellable
object,None
to ignore
- set_display_name_async(display_name: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sets the display name for a given
File
.For more details, see
set_display_name()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callset_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- set_display_name_finish(res: AsyncResult) File #
Finishes setting a display name started with
set_display_name_async()
.- Parameters:
res – a
AsyncResult
- start_mountable(flags: DriveStartFlags, start_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts a file of type
MOUNTABLE
. Usingstart_operation
, you can request callbacks when, for instance, passwords are needed during authentication.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
start_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- start_mountable_finish(result: AsyncResult) bool #
Finishes a start operation. See
start_mountable()
for details.Finish an asynchronous start operation that was started with
start_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- stop_mountable(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Stops a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callstop_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interaction.cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- stop_mountable_finish(result: AsyncResult) bool #
Finishes a stop operation, see
stop_mountable()
for details.Finish an asynchronous stop operation that was started with
stop_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- supports_thread_contexts() bool #
Checks if
file
supports [thread-default contexts][g-main-context-push-thread-default-context]. If this returnsFalse
, you cannot perform asynchronous operations onfile
in a thread that has a thread-default context.Added in version 2.22.
- trash(cancellable: Cancellable | None = 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 (seeunix_mount_is_system_internal()
), so this call can return theNOT_SUPPORTED
error. Since GLib 2.66, thex-gvfs-notrash
unix mount option can be used to disabletrash()
support for particular mounts, theNOT_SUPPORTED
error will be returned in that case. Since 2.82, thex-gvfs-trash
unix mount option can be used to enabletrash()
support for particular system mounts.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- trash_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sends
file
to the Trash location, if possible.Added in version 2.38.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- trash_finish(result: AsyncResult) bool #
Finishes an asynchronous file trashing operation, started with
trash_async()
.Added in version 2.38.
- Parameters:
result – a
AsyncResult
- unmount_mountable(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callunmount_mountable_finish()
to get the result of the operation.Deprecated since version 2.22: Use
unmount_mountable_with_operation()
instead.- Parameters:
flags – flags affecting the operation
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- unmount_mountable_finish(result: AsyncResult) bool #
Finishes an unmount operation, see
unmount_mountable()
for details.Finish an asynchronous unmount operation that was started with
unmount_mountable()
.Deprecated since version 2.22: Use
unmount_mountable_with_operation_finish()
instead.- Parameters:
result – a
AsyncResult
- unmount_mountable_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Unmounts a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callunmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- unmount_mountable_with_operation_finish(result: AsyncResult) bool #
Finishes an unmount operation, see
unmount_mountable_with_operation()
for details.Finish an asynchronous unmount operation that was started with
unmount_mountable_with_operation()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
Virtual Methods#
- class File
- do_append_to(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Some file systems don’t allow all file names, and may return an
INVALID_FILENAME
error. If the file is a directory theIS_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(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for appending.For more details, see
append_to()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callappend_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_append_to_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file append operation started with
append_to_async()
.- Parameters:
res –
AsyncResult
- do_copy(destination: File, flags: FileCopyFlags, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, *progress_callback_data: Any) bool #
Copies the file
source
to the location specified bydestination
. Can not handle recursive copies of directories.If the flag
OVERWRITE
is specified an already existingdestination
file is overwritten.If the flag
NOFOLLOW_SYMLINKS
is specified then symlinks will be copied as symlinks, otherwise the target of thesource
symlink will be copied.If the flag
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, seeFileInfo
).If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
progress_callback
is notNone
, then the operation can be monitored by setting this to aFileProgressCallback
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 theNOT_FOUND
error is returned, independent on the status of thedestination
.If
OVERWRITE
is not specified and the target exists, then the errorEXISTS
is returned.If trying to overwrite a file over a directory, the
IS_DIRECTORY
error is returned. If trying to overwrite a directory with a directory theWOULD_MERGE
error is returned.If the source is a directory and the target does not exist, or
OVERWRITE
is specified and the target is a file, then theWOULD_RECURSE
error is returned.If you are interested in copying the
File
object itself (not the on-disk file), seedup()
.- Parameters:
destination – destination
File
flags – set of
FileCopyFlags
cancellable – optional
Cancellable
object,None
to ignoreprogress_callback – function to callback with progress information, or
None
if progress information is not neededprogress_callback_data – user data to pass to
progress_callback
- do_copy_async(destination: File, flags: FileCopyFlags, io_priority: int, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Copies the file
source
to the location specified bydestination
asynchronously. For details of the behaviour, seecopy()
.If
progress_callback
is notNone
, then that function that will be called just like incopy()
. The callback will run in the default main context of the thread callingcopy_async()
— the same context ascallback
is run in.When the operation is finished,
callback
will be called. You can then callcopy_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 ignoreprogress_callback – function to callback with progress information, or
None
if progress information is not neededcallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback
- do_copy_finish(res: AsyncResult) bool #
Finishes copying the file started with
copy_async()
.- Parameters:
res – a
AsyncResult
- do_create(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If a file or directory with this name already exists the
EXISTS
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is to longFILENAME_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(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
create()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callcreate_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_create_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file create operation started with
create_async()
.- Parameters:
res – a
AsyncResult
- do_create_readwrite(flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If a file or directory with this name already exists, the
EXISTS
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is too long,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.
Added in version 2.22.
- Parameters:
flags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_create_readwrite_async(flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
create_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callcreate_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_create_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file create operation started with
create_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- do_delete_file(cancellable: Cancellable | None = None) bool #
The type of the None singleton.
- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_delete_file_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
The type of the None singleton.
Added in version 2.34.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_delete_file_finish(result: AsyncResult) bool #
The type of the None singleton.
Added in version 2.34.
- Parameters:
result – a
AsyncResult
- do_dup() File #
Duplicates a
File
handle. This operation does not duplicate the actual file or directory represented by theFile
; seecopy()
if attempting to copy a 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, useref()
to increment the existing object’s reference count.This call does no blocking I/O.
- do_eject_mountable(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous eject on a mountable. When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized witheject_mountable_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Deprecated since version 2.22: Use
eject_mountable_with_operation()
instead.- Parameters:
flags – flags affecting the operation
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_eject_mountable_finish(result: AsyncResult) bool #
Finishes an asynchronous eject operation started by
eject_mountable()
.Deprecated since version 2.22: Use
eject_mountable_with_operation_finish()
instead.- Parameters:
result – a
AsyncResult
- do_eject_mountable_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts an asynchronous eject on a mountable. When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized witheject_mountable_with_operation_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_eject_mountable_with_operation_finish(result: AsyncResult) bool #
Finishes an asynchronous eject operation started by
eject_mountable_with_operation()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- do_enumerate_children(attributes: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) FileEnumerator #
Gets the requested information about the files in a directory. The result is a
FileEnumerator
object that will give outFileInfo
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, likeFILE_ATTRIBUTE_STANDARD_NAME
.FILE_ATTRIBUTE_STANDARD_NAME
should always be specified if you plan to callget_child()
oriterate()
on the returned enumerator.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
NOT_FOUND
error will be returned. If the file is not a directory, theNOT_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(attributes: str, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about the files in a directory. The result is a
FileEnumerator
object that will give outFileInfo
objects for all the files in the directory.For more details, see
enumerate_children()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callenumerate_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_enumerate_children_finish(res: AsyncResult) FileEnumerator #
Finishes an async enumerate children operation. See
enumerate_children_async()
.- Parameters:
res – a
AsyncResult
- do_equal(file2: File) bool #
Checks if the two given
File
refer to the same file.Note that two
File
that differ can still refer to the same file on the filesystem due to various forms of filename aliasing.This call does no blocking I/O.
- Parameters:
file2 – the second
File
- do_find_enclosing_mount(cancellable: Cancellable | None = None) Mount #
-
Mount
is returned only for user interesting locations, seeVolumeMonitor
. If theGFileIface
forfile
does not have amount
,error
will be set toNOT_FOUND
andNone
will
be returned.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_find_enclosing_mount_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the mount for the file.
For more details, see
find_enclosing_mount()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callfind_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_find_enclosing_mount_finish(res: AsyncResult) Mount #
Finishes an asynchronous find mount request. See
find_enclosing_mount_async()
.- Parameters:
res – a
AsyncResult
- do_get_basename() 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 withquery_info()
.This call does no blocking I/O.
- do_get_child_for_display_name(display_name: str) File #
Gets the child of
file
for a givendisplay_name
(i.e. a UTF-8 version of the name). If this function fails, it returnsNone
anderror
will be set. This is very useful when constructing aFile
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() File | None #
Gets the parent directory for the
file
. If thefile
represents the root directory of the file system, thenNone
will be returned.This call does no blocking I/O.
- do_get_parse_name() 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 theFile
back usingparse_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() 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(descendant: File) str | None #
Gets the path for
descendant
relative toparent
.This call does no blocking I/O.
- Parameters:
descendant – input
File
- do_get_uri_scheme() 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 theFile
.This call does no blocking I/O.
- do_has_uri_scheme(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_is_native() 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
, butget_path()
will still return a native path.This call does no blocking I/O.
- do_make_directory(cancellable: Cancellable | None = 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, seemake_directory_with_parents()
. This function will fail if the parent directory does not exist, settingerror
toNOT_FOUND
. If the file system doesn’t support creating directories, this function will fail, settingerror
toNOT_SUPPORTED
.For a local
File
the newly created directory will have the default (current) ownership and permissions of the current process.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_make_directory_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously creates a directory.
Added in version 2.38.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_make_directory_finish(result: AsyncResult) bool #
Finishes an asynchronous directory creation, started with
make_directory_async()
.Added in version 2.38.
- Parameters:
result – a
AsyncResult
- do_make_symbolic_link(symlink_value: str, cancellable: Cancellable | None = None) bool #
Creates a symbolic link named
file
which contains the stringsymlink_value
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(symlink_value: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously creates a symbolic link named
file
which contains the stringsymlink_value
.Added in version 2.74.
- 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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_make_symbolic_link_finish(result: AsyncResult) bool #
Finishes an asynchronous symbolic link creation, started with
make_symbolic_link_async()
.Added in version 2.74.
- Parameters:
result – a
AsyncResult
- do_measure_disk_usage(flags: FileMeasureFlags, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, *progress_data: Any) 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
REPORT_ANY_ERROR
is given inflags
.The returned size,
disk_usage
, is in bytes and should be formatted withformat_size()
in order to get something reasonable for showing in a user interface.progress_callback
andprogress_data
can be given to request periodic progress updates while scanning. See the documentation forFileMeasureProgressCallback
for information about when and how the callback will be invoked.Added in version 2.38.
- Parameters:
flags –
FileMeasureFlags
cancellable – optional
Cancellable
progress_callback – a
FileMeasureProgressCallback
progress_data – user_data for
progress_callback
- do_measure_disk_usage_finish(result: AsyncResult) tuple[bool, int, int, int] #
Collects the results from an earlier call to
measure_disk_usage_async()
. Seemeasure_disk_usage()
for more information.Added in version 2.38.
- Parameters:
result – the
AsyncResult
passed to yourAsyncReadyCallback
- do_monitor_dir(flags: FileMonitorFlags, cancellable: Cancellable | None = None) FileMonitor #
The type of the None singleton.
- Parameters:
flags – a set of
FileMonitorFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_monitor_file(flags: FileMonitorFlags, cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
flags
containsWATCH_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 infile
to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on theFileMonitor
backend and/or filesystem type.- Parameters:
flags – a set of
FileMonitorFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_mount_enclosing_volume(flags: MountMountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts a
mount_operation
, mounting the volume that contains the filelocation
.When this operation has completed,
callback
will be called withuser_user
data, and the operation can be finalized withmount_enclosing_volume_finish()
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- do_mount_enclosing_volume_finish(result: AsyncResult) bool #
Finishes a mount operation started by
mount_enclosing_volume()
.- Parameters:
result – a
AsyncResult
- do_mount_mountable(flags: MountMountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_mount_mountable_finish(result: AsyncResult) File #
Finishes a mount operation. See
mount_mountable()
for details.Finish an asynchronous mount operation that was started with
mount_mountable()
.- Parameters:
result – a
AsyncResult
- do_move(destination: File, flags: FileCopyFlags, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, *progress_callback_data: Any) bool #
Tries to move the file or directory
source
to the location specified bydestination
. 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
OVERWRITE
is specified an already existingdestination
file is overwritten.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If
progress_callback
is notNone
, then the operation can be monitored by setting this to aFileProgressCallback
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 theNOT_FOUND
error is returned, independent on the status of thedestination
.If
OVERWRITE
is not specified and the target exists, then the errorEXISTS
is returned.If trying to overwrite a file over a directory, the
IS_DIRECTORY
error is returned. If trying to overwrite a directory with a directory theWOULD_MERGE
error is returned.If the source is a directory and the target does not exist, or
OVERWRITE
is specified and the target is a file, then theWOULD_RECURSE
error may be returned (if the native move operation isn’t available).- Parameters:
destination –
File
pointing to the destination locationflags – set of
FileCopyFlags
cancellable – optional
Cancellable
object,None
to ignoreprogress_callback –
FileProgressCallback
function for updatesprogress_callback_data – gpointer to user data for the callback function
- do_move_async(destination: File, flags: FileCopyFlags, io_priority: int, cancellable: Cancellable | None = None, progress_callback: Callable[[...], None] | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously moves a file
source
to the location ofdestination
. For details of the behaviour, seemove()
.If
progress_callback
is notNone
, then that function that will be called just like inmove()
. The callback will run in the default main context of the thread callingmove_async()
— the same context ascallback
is run in.When the operation is finished,
callback
will be called. You can then callmove_finish()
to get the result of the operation.Added in version 2.72.
- Parameters:
destination –
File
pointing to the destination locationflags – set of
FileCopyFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignoreprogress_callback –
FileProgressCallback
function for updatescallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_move_finish(result: AsyncResult) bool #
Finishes an asynchronous file movement, started with
move_async()
.Added in version 2.72.
- Parameters:
result – a
AsyncResult
- do_open_readwrite(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
NOT_FOUND
error will be returned. If the file is a directory, theIS_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.Added in version 2.22.
- Parameters:
cancellable – a
Cancellable
- do_open_readwrite_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for reading and writing.For more details, see
open_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callopen_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_open_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file read operation started with
open_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- do_poll_mountable(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Polls a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- do_poll_mountable_finish(result: AsyncResult) bool #
Finishes a poll operation. See
poll_mountable()
for details.Finish an asynchronous poll operation that was polled with
poll_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- do_query_filesystem_info(attributes: str, cancellable: Cancellable | None = None) FileInfo #
Similar to
query_info()
, but obtains information about the filesystem thefile
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 areFILE_ATTRIBUTE_FILESYSTEM_SIZE
(the total size of the filesystem in bytes),FILE_ATTRIBUTE_FILESYSTEM_FREE
(number of bytes available), andFILE_ATTRIBUTE_FILESYSTEM_TYPE
(type of the filesystem).If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If the file does not exist, the
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(attributes: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about the filesystem that the specified
file
is on. The result is aFileInfo
object that contains key-value attributes (such as type or size for the file).For more details, see
query_filesystem_info()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callquery_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_query_filesystem_info_finish(res: AsyncResult) FileInfo #
Finishes an asynchronous filesystem info query. See
query_filesystem_info_async()
.- Parameters:
res – a
AsyncResult
- do_query_info(attributes: str, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) FileInfo #
Gets the requested information about specified
file
. The result is aFileInfo
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.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, likeFILE_ATTRIBUTE_STANDARD_NAME
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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
NOFOLLOW_SYMLINKS
inflags
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
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
flags – a set of
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_query_info_async(attributes: str, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously gets the requested information about specified
file
. The result is aFileInfo
object that contains key-value attributes (such as type or size for the file).For more details, see
query_info()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callquery_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_query_info_finish(res: AsyncResult) FileInfo #
Finishes an asynchronous file info query. See
query_info_async()
.- Parameters:
res – a
AsyncResult
- do_query_settable_attributes(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_query_writable_namespaces(cancellable: Cancellable | None = 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 notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_read_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously opens
file
for reading.For more details, see
read()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callread_finish()
to get the result of the operation.- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_read_finish(res: AsyncResult) FileInputStream #
Finishes an asynchronous file read operation started with
read_async()
.- Parameters:
res – a
AsyncResult
- do_read_fn(cancellable: Cancellable | None = None) FileInputStream #
The type of the None singleton.
- Parameters:
cancellable – a
Cancellable
- do_replace(etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = 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
PRIVATE
inflags
the file will be made readable only to the current user, to the level that is supported on the target filesystem.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.If you pass in a non-
None
etag
value andfile
already exists, then this value is compared to the current entity tag of the file, and if they differ anWRONG_ETAG
error is returned. This generally means that the file has been changed since you last read it. You can get the new etag fromget_etag()
after you’ve finished writing and closed theFileOutputStream
. When you load a new file you can usequery_info()
to get the etag of the file.If
make_backup
isTrue
, this function will attempt to make a backup of the current file before overwriting it. If this fails aCANT_CREATE_BACKUP
error will be returned. If you want to replace anyway, try again withmake_backup
set toFalse
.If the file is a directory the
IS_DIRECTORY
error will be returned, and if the file is some other form of non-regular file then aNOT_REGULAR_FILE
error will be returned. Some file systems don’t allow all file names, and may return anINVALID_FILENAME
error, and if the name is to longFILENAME_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 <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_replace_async(etag: str | None, make_backup: bool, flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.
For more details, see
replace()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callreplace_finish()
to get the result of the operation.- Parameters:
etag – an
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_replace_finish(res: AsyncResult) FileOutputStream #
Finishes an asynchronous file replace operation started with
replace_async()
.- Parameters:
res – a
AsyncResult
- do_replace_readwrite(etag: str | None, make_backup: bool, flags: FileCreateFlags, cancellable: Cancellable | None = 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
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.
Added in version 2.22.
- Parameters:
etag – an optional
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_replace_readwrite_async(etag: str | None, make_backup: bool, flags: FileCreateFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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
replace_readwrite()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callreplace_readwrite_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
etag – an
entity tag <``entity`
-tags>`_ for the currentFile
, orNone
to ignoremake_backup –
True
if a backup should be createdflags – a set of
FileCreateFlags
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_replace_readwrite_finish(res: AsyncResult) FileIOStream #
Finishes an asynchronous file replace operation started with
replace_readwrite_async()
.Added in version 2.22.
- Parameters:
res – a
AsyncResult
- do_resolve_relative_path(relative_path: str) 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 takingfile
path as base).- Parameters:
relative_path – a given relative path string
- do_set_attribute(attribute: str, type: FileAttributeType, value_p: None, flags: FileQueryInfoFlags, cancellable: Cancellable | None = None) bool #
Sets an attribute in the file with attribute name
attribute
tovalue_p
.Some attributes can be unset by setting
type
toINVALID
andvalue_p
toNone
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
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(info: FileInfo, flags: FileQueryInfoFlags, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sets the attributes of
file
withinfo
.For more details, see
set_attributes_from_info()
, which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callset_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_set_attributes_finish(result: AsyncResult) tuple[bool, FileInfo] #
Finishes setting an attribute started in
set_attributes_async()
.- Parameters:
result – a
AsyncResult
- do_set_attributes_from_info(info: FileInfo, flags: FileQueryInfoFlags, cancellable: Cancellable | None = 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 toERROR_SETTING
, which means you can also detect further errors.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
info – a
FileInfo
flags –
FileQueryInfoFlags
cancellable – optional
Cancellable
object,None
to ignore
- do_set_display_name(display_name: str, cancellable: Cancellable | None = 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 toset_display_name()
.On success the resulting converted filename is returned.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
display_name – a string
cancellable – optional
Cancellable
object,None
to ignore
- do_set_display_name_async(display_name: str, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sets the display name for a given
File
.For more details, see
set_display_name()
which is the synchronous version of this call.When the operation is finished,
callback
will be called. You can then callset_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 ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_set_display_name_finish(res: AsyncResult) File #
Finishes setting a display name started with
set_display_name_async()
.- Parameters:
res – a
AsyncResult
- do_start_mountable(flags: DriveStartFlags, start_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Starts a file of type
MOUNTABLE
. Usingstart_operation
, you can request callbacks when, for instance, passwords are needed during authentication.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
start_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- do_start_mountable_finish(result: AsyncResult) bool #
Finishes a start operation. See
start_mountable()
for details.Finish an asynchronous start operation that was started with
start_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- do_stop_mountable(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Stops a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callstop_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interaction.cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfied, orNone
user_data – the data to pass to callback function
- do_stop_mountable_finish(result: AsyncResult) bool #
Finishes a stop operation, see
stop_mountable()
for details.Finish an asynchronous stop operation that was started with
stop_mountable()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult
- do_trash(cancellable: Cancellable | None = 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 (seeunix_mount_is_system_internal()
), so this call can return theNOT_SUPPORTED
error. Since GLib 2.66, thex-gvfs-notrash
unix mount option can be used to disabletrash()
support for particular mounts, theNOT_SUPPORTED
error will be returned in that case. Since 2.82, thex-gvfs-trash
unix mount option can be used to enabletrash()
support for particular system mounts.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.- Parameters:
cancellable – optional
Cancellable
object,None
to ignore
- do_trash_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Asynchronously sends
file
to the Trash location, if possible.Added in version 2.38.
- Parameters:
io_priority –
the I/O priority of the request
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_trash_finish(result: AsyncResult) bool #
Finishes an asynchronous file trashing operation, started with
trash_async()
.Added in version 2.38.
- Parameters:
result – a
AsyncResult
- do_unmount_mountable(flags: MountUnmountFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callunmount_mountable_finish()
to get the result of the operation.Deprecated since version 2.22: Use
unmount_mountable_with_operation()
instead.- Parameters:
flags – flags affecting the operation
cancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_unmount_mountable_finish(result: AsyncResult) bool #
Finishes an unmount operation, see
unmount_mountable()
for details.Finish an asynchronous unmount operation that was started with
unmount_mountable()
.Deprecated since version 2.22: Use
unmount_mountable_with_operation_finish()
instead.- Parameters:
result – a
AsyncResult
- do_unmount_mountable_with_operation(flags: MountUnmountFlags, mount_operation: MountOperation | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Unmounts a file of type
MOUNTABLE
.If
cancellable
is notNone
, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned.When the operation is finished,
callback
will be called. You can then callunmount_mountable_finish()
to get the result of the operation.Added in version 2.22.
- Parameters:
flags – flags affecting the operation
mount_operation – a
MountOperation
, orNone
to avoid user interactioncancellable – optional
Cancellable
object,None
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- do_unmount_mountable_with_operation_finish(result: AsyncResult) bool #
Finishes an unmount operation, see
unmount_mountable_with_operation()
for details.Finish an asynchronous unmount operation that was started with
unmount_mountable_with_operation()
.Added in version 2.22.
- Parameters:
result – a
AsyncResult