QFile¶
Inherited by: QTemporaryFile
Synopsis¶
Functions¶
def
copy
(newName)def
exists
()def
link
(newName)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
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:
file = QFile("in.txt") if not file.open(QIODevice.ReadOnly | QIODevice.Text): return while not file.atEnd(): line = file.readLine() # A QByteArray 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:file = QFile("in.txt") if not file.open(QIODevice.ReadOnly | QIODevice.Text): return in = QTextStream(file) while not in.atEnd(): line = in.readLine() # A QByteArray 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:file = QFile("out.txt") if not file.open(QIODevice.WriteOnly | QIODevice.Text): return out = QTextStream(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:file = QFile("/proc/modules") if not file.open(QIODevice.ReadOnly | QIODevice.Text): return in = QTextStream(file) line = in.readLine() while not line.isNull(): process_line(line) line = in.readLine()
Signals¶
Unlike other
QIODevice
implementations, such asQTcpSocket
,QFile
does not emit theaboutToClose()
,bytesWritten()
, orreadyRead()
signals. This implementation detail means thatQFile
is not suitable for reading and writing certain types of files, such as device files on Unix platforms.
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
QFile
¶ QFile(parent)
QFile(name)
QFile(name, parent)
- param parent
- param name
unicode
Constructs a
QFile
object.Constructs a new file object with the given
parent
.
-
static
PySide2.QtCore.QFile.
copy
(fileName, newName)¶ - Parameters
fileName – unicode
newName – unicode
- Return type
bool
This is an overloaded function.
Copies the file
fileName
tonewName
. Returnstrue
if successful; otherwise returnsfalse
.If a file with the name
newName
already exists,copy()
returnsfalse
(i.e.,QFile
will not overwrite it).See also
-
PySide2.QtCore.QFile.
copy
(newName) - Parameters
newName – unicode
- Return type
bool
Copies the file currently specified by
fileName()
to a file callednewName
. Returnstrue
if successful; otherwise returnsfalse
.Note that if a file with the name
newName
already exists, returnsfalse
(i.e.QFile
will not overwrite it).The source file is closed before it is copied.
See also
-
static
PySide2.QtCore.QFile.
decodeName
(localFileName)¶ - Parameters
localFileName –
QByteArray
- Return type
unicode
-
static
PySide2.QtCore.QFile.
decodeName
(localFileName) - Parameters
localFileName – str
- Return type
unicode
This is an overloaded function.
Returns the Unicode version of the given
localFileName
. SeeencodeName()
for details.
-
static
PySide2.QtCore.QFile.
encodeName
(fileName)¶ - Parameters
fileName – unicode
- 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 – unicode
- 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 – unicode
- 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 – unicode
newName – unicode
- 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.
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.The
QFile
that is opened using this function is automatically set to be in raw mode; this means that the file input/output functions are slow. If you run into performance issues, you should try to use one of the other open functions.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 – unicode
- Return type
Permissions
This is an overloaded function.
Returns the complete OR-ed together combination of
Permission
forfileName
.
-
PySide2.QtCore.QFile.
readLink
()¶ - Return type
unicode
Use
symLinkTarget()
instead.
-
static
PySide2.QtCore.QFile.
readLink
(fileName) - Parameters
fileName – unicode
- Return type
unicode
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 – unicode
- 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 – unicode
- 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 – unicode
newName – unicode
- 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 – unicode
sz –
qint64
- 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 – unicode
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 – unicode
permissionSpec –
Permissions
- Return type
bool
This is an overloaded function.
Sets the permissions for
fileName
file topermissions
.
-
PySide2.QtCore.QFile.
symLinkTarget
()¶ - Return type
unicode
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 – unicode
- Return type
unicode
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.
© 2018 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.