QFile¶
Inherited by: QTemporaryFile
Synopsis¶
Functions¶
def
copy
(newName)def
exists
()def
link
(newName)def
moveToTrash
()def
open
(fd, ioFlags[, handleFlags=QFileDevice.DontCloseHandle])def
readLink
()def
remove
()def
rename
(newName)def
setFileName
(name)def
symLinkTarget
()
Static functions¶
def
copy
(fileName, newName)def
decodeName
(localFileName)def
decodeName
(localFileName)def
encodeName
(fileName)def
exists
(fileName)def
link
(oldname, newName)def
moveToTrash
(fileName[, pathInTrash=None])def
permissions
(filename)def
readLink
(fileName)def
remove
(fileName)def
rename
(oldName, newName)def
resize
(filename, sz)def
setPermissions
(filename, permissionSpec)def
symLinkTarget
(fileName)
Detailed Description¶
QFile
is an I/O device for reading and writing text and binary files and resources . AQFile
may be used by itself or, more conveniently, with aQTextStream
orQDataStream
.The file name is usually passed in the constructor, but it can be set at any time using
setFileName()
.QFile
expects the file separator to be ‘/’ regardless of operating system. The use of other separators (e.g., ‘\’) is not supported.You can check for a file’s existence using
exists()
, and remove a file usingremove()
. (More advanced file system related operations are provided byQFileInfo
andQDir
.)The file is opened with
open()
, closed withclose()
, and flushed withflush()
. Data is usually read and written usingQDataStream
orQTextStream
, but you can also call theQIODevice
-inherited functionsread()
,readLine()
,readAll()
,write()
.QFile
also inheritsgetChar()
,putChar()
, andungetChar()
, which work one character at a time.The size of the file is returned by
size()
. You can get the current file position usingpos()
, or move to a new file position usingseek()
. If you’ve reached the end of the file,atEnd()
returnstrue
.
Reading Files Directly¶
The following example reads a text file line by line:
QFile file("in.txt"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; while (!file.atEnd()) { QByteArray line = file.readLine(); process_line(line); }The
Text
flag passed toopen()
tells Qt to convert Windows-style line terminators (”\r\n”) into C++-style terminators (”\n”). By default,QFile
assumes binary, i.e. it doesn’t perform any conversion on the bytes stored in the file.
Using Streams to Read Files¶
The next example uses
QTextStream
to read a text file line by line:QFile file("in.txt"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; QTextStream in(&file); while (!in.atEnd()) { QString line = in.readLine(); process_line(line); }
QTextStream
takes care of converting the 8-bit data stored on disk into a 16-bit UnicodeQString
. By default, it assumes that the user system’s local 8-bit encoding is used (e.g., UTF-8 on most unix based operating systems; seecodecForLocale()
for details). This can be changed usingsetCodec()
.To write text, we can use operator<<(), which is overloaded to take a
QTextStream
on the left and various data types (includingQString
) on the right:QFile file("out.txt"); if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) return; QTextStream out(&file); out << "The magic number is: " << 49 << "\n";
QDataStream
is similar, in that you can use operator<<() to write data and operator>>() to read it back. See the class documentation for details.When you use
QFile
,QFileInfo
, andQDir
to access the file system with Qt, you can use Unicode file names. On Unix, these file names are converted to an 8-bit encoding. If you want to use standard C++ APIs (<cstdio>
or<iostream>
) or platform-specific APIs to access files instead ofQFile
, you can use theencodeName()
anddecodeName()
functions to convert between Unicode file names and 8-bit file names.On Unix, there are some special system files (e.g. in
/proc
) for whichsize()
will always return 0, yet you may still be able to read more data from such a file; the data is generated in direct response to you callingread()
. In this case, however, you cannot useatEnd()
to determine if there is more data to read (sinceatEnd()
will return true for a file that claims to have size 0). Instead, you should either callreadAll()
, or callread()
orreadLine()
repeatedly until no more data can be read. The next example usesQTextStream
to read/proc/modules
line by line:QFile file("/proc/modules"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; QTextStream in(&file); QString line = in.readLine(); while (!line.isNull()) { process_line(line); line = in.readLine(); }
Signals¶
Platform Specific Issues¶
File permissions are handled differently on Unix-like systems and Windows. In a non
writable
directory on Unix-like systems, files cannot be created. This is not always the case on Windows, where, for instance, the ‘My Documents’ directory usually is not writable, but it is still possible to create files in it.Qt’s understanding of file permissions is limited, which affects especially the
setPermissions()
function. On Windows, Qt will set only the legacy read-only flag, and that only when none of the Write* flags are passed. Qt does not manipulate access control lists (ACLs), which makes this function mostly useless for NTFS volumes. It may still be of use for USB sticks that use VFAT file systems. POSIX ACLs are not manipulated, either.
- class PySide2.QtCore.QFile¶
PySide2.QtCore.QFile(parent)
PySide2.QtCore.QFile(name)
PySide2.QtCore.QFile(name, parent)
- param parent:
- param name:
str
Constructs a
QFile
object.Constructs a new file object with the given
parent
.
- static PySide2.QtCore.QFile.copy(fileName, newName)¶
- Parameters:
fileName – str
newName – str
- Return type:
bool
This is an overloaded function.
Copies the file named
fileName
tonewName
.This file is closed before it is copied.
If the copied file is a symbolic link (symlink), the file it refers to is copied, not the link itself. With the exception of permissions, which are copied, no other file metadata is copied.
Returns
true
if successful; otherwise returnsfalse
.Note that if a file with the name
newName
already exists,copy()
returnsfalse
. This meansQFile
will not overwrite it.See also
- PySide2.QtCore.QFile.copy(newName)
- Parameters:
newName – str
- Return type:
bool
Copies the file named
fileName()
tonewName
.This file is closed before it is copied.
If the copied file is a symbolic link (symlink), the file it refers to is copied, not the link itself. With the exception of permissions, which are copied, no other file metadata is copied.
Returns
true
if successful; otherwise returnsfalse
.Note that if a file with the name
newName
already exists, returnsfalse
. This meansQFile
will not overwrite it.See also
- static PySide2.QtCore.QFile.decodeName(localFileName)¶
- Parameters:
localFileName –
PySide2.QtCore.QByteArray
- Return type:
str
- static PySide2.QtCore.QFile.decodeName(localFileName)
- Parameters:
localFileName – str
- Return type:
str
This is an overloaded function.
Returns the Unicode version of the given
localFileName
. SeeencodeName()
for details.
- static PySide2.QtCore.QFile.encodeName(fileName)¶
- Parameters:
fileName – str
- Return type:
Converts
fileName
to the local 8-bit encoding determined by the user’s locale. This is sufficient for file names that the user chooses. File names hard-coded into the application should only use 7-bit ASCII filename characters.See also
- PySide2.QtCore.QFile.exists()¶
- Return type:
bool
This is an overloaded function.
Returns
true
if the file specified byfileName()
exists; otherwise returnsfalse
.See also
fileName()
setFileName()
- static PySide2.QtCore.QFile.exists(fileName)
- Parameters:
fileName – str
- Return type:
bool
Returns
true
if the file specified byfileName
exists; otherwise returnsfalse
.Note
If
fileName
is a symlink that points to a non-existing file, false is returned.
- PySide2.QtCore.QFile.link(newName)¶
- Parameters:
newName – str
- Return type:
bool
Creates a link named
linkName
that points to the file currently specified byfileName()
. What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Unix). Returnstrue
if successful; otherwise returnsfalse
.This function will not overwrite an already existing entity in the file system; in this case,
link()
will return false and seterror()
to returnRenameError
.Note
To create a valid link on Windows,
linkName
must have a.lnk
file extension.See also
- static PySide2.QtCore.QFile.link(oldname, newName)
- Parameters:
oldname – str
newName – str
- Return type:
bool
This is an overloaded function.
Creates a link named
linkName
that points to the filefileName
. What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Unix). Returnstrue
if successful; otherwise returnsfalse
.See also
- PySide2.QtCore.QFile.moveToTrash()¶
- Return type:
bool
Moves the file specified by
fileName()
to the trash. Returnstrue
if successful, and sets thefileName()
to the path at which the file can be found within the trash; otherwise returnsfalse
.Note
On systems where the system API doesn’t report the location of the file in the trash,
fileName()
will be set to the null string once the file has been moved. On systems that don’t have a trash can, this function always returns false.
- static PySide2.QtCore.QFile.moveToTrash(fileName[, pathInTrash=None])
- Parameters:
fileName – str
pathInTrash – str
- Return type:
bool
This is an overloaded function.
Moves the file specified by
fileName()
to the trash. Returnstrue
if successful, and setspathInTrash
(if provided) to the path at which the file can be found within the trash; otherwise returnsfalse
.Note
On systems where the system API doesn’t report the path of the file in the trash,
pathInTrash
will be set to the null string once the file has been moved. On systems that don’t have a trash can, this function always returns false.
- PySide2.QtCore.QFile.open(fd, ioFlags[, handleFlags=QFileDevice.DontCloseHandle])¶
- Parameters:
fd – int
ioFlags –
OpenMode
handleFlags –
FileHandleFlags
- Return type:
bool
This is an overloaded function.
Opens the existing file descriptor
fd
in the givenmode
.handleFlags
may be used to specify additional options. Returnstrue
if successful; otherwise returnsfalse
.When a
QFile
is opened using this function, behaviour ofclose()
is controlled by theAutoCloseHandle
flag. IfAutoCloseHandle
is specified, and this function succeeds, then callingclose()
closes the adopted handle. Otherwise,close()
does not actually close the file, but only flushes it.Warning
If
fd
is not a regular file, e.g, it is 0 (stdin
), 1 (stdout
), or 2 (stderr
), you may not be able toseek()
. In those cases,size()
returns0
. SeeisSequential()
for more information.Warning
Since this function opens the file without specifying the file name, you cannot use this
QFile
with aQFileInfo
.See also
close()
- static PySide2.QtCore.QFile.permissions(filename)¶
- Parameters:
filename – str
- Return type:
Permissions
This is an overloaded function.
Returns the complete OR-ed together combination of
Permission
forfileName
.
- PySide2.QtCore.QFile.readLink()¶
- Return type:
str
Note
This function is deprecated.
Use
symLinkTarget()
instead.
- static PySide2.QtCore.QFile.readLink(fileName)
- Parameters:
fileName – str
- Return type:
str
Note
This function is deprecated.
Use
symLinkTarget()
instead.
- PySide2.QtCore.QFile.remove()¶
- Return type:
bool
Removes the file specified by
fileName()
. Returnstrue
if successful; otherwise returnsfalse
.The file is closed before it is removed.
See also
- static PySide2.QtCore.QFile.remove(fileName)
- Parameters:
fileName – str
- Return type:
bool
This is an overloaded function.
Removes the file specified by the
fileName
given.Returns
true
if successful; otherwise returnsfalse
.See also
- PySide2.QtCore.QFile.rename(newName)¶
- Parameters:
newName – str
- Return type:
bool
Renames the file currently specified by
fileName()
tonewName
. Returnstrue
if successful; otherwise returnsfalse
.If a file with the name
newName
already exists, returnsfalse
(i.e.,QFile
will not overwrite it).The file is closed before it is renamed.
If the rename operation fails, Qt will attempt to copy this file’s contents to
newName
, and then remove this file, keeping onlynewName
. If that copy operation fails or this file can’t be removed, the destination filenewName
is removed to restore the old state.See also
- static PySide2.QtCore.QFile.rename(oldName, newName)
- Parameters:
oldName – str
newName – str
- Return type:
bool
This is an overloaded function.
Renames the file
oldName
tonewName
. Returnstrue
if successful; otherwise returnsfalse
.If a file with the name
newName
already exists,rename()
returnsfalse
(i.e.,QFile
will not overwrite it).See also
- static PySide2.QtCore.QFile.resize(filename, sz)¶
- Parameters:
filename – str
sz – int
- Return type:
bool
This is an overloaded function.
Sets
fileName
to size (in bytes)sz
. Returnstrue
if the resize succeeds; false otherwise. Ifsz
is larger thanfileName
currently is the new bytes will be set to 0, ifsz
is smaller the file is simply truncated.Warning
This function can fail if the file doesn’t exist.
See also
- PySide2.QtCore.QFile.setFileName(name)¶
- Parameters:
name – str
Sets the
name
of the file. The name can have no path, a relative path, or an absolute path.Do not call this function if the file has already been opened.
If the file name has no path or a relative path, the path used will be the application’s current directory path at the time of the
open()
** call.Example:
file = QFile() QDir.setCurrent("/tmp") file.setFileName("readme.txt") QDir.setCurrent("/home") file.open(QIODevice.ReadOnly) # opens "/home/readme.txt" under Unix
Note that the directory separator “/” works for all operating systems supported by Qt.
- static PySide2.QtCore.QFile.setPermissions(filename, permissionSpec)¶
- Parameters:
filename – str
permissionSpec –
Permissions
- Return type:
bool
This is an overloaded function.
Sets the permissions for
fileName
file topermissions
.
- PySide2.QtCore.QFile.symLinkTarget()¶
- Return type:
str
This is an overloaded function.
Returns the absolute path of the file or directory a symlink (or shortcut on Windows) points to, or a an empty string if the object isn’t a symbolic link.
This name may not represent an existing file; it is only a string.
exists()
returnstrue
if the symlink points to an existing file.See also
fileName()
setFileName()
- static PySide2.QtCore.QFile.symLinkTarget(fileName)
- Parameters:
fileName – str
- Return type:
str
Returns the absolute path of the file or directory referred to by the symlink (or shortcut on Windows) specified by
fileName
, or returns an empty string if thefileName
does not correspond to a symbolic link.This name may not represent an existing file; it is only a string.
exists()
returnstrue
if the symlink points to an existing file.
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.