class QFile#

QFile类提供了一个用于从文件读取和写入的接口。更多…

Inheritance diagram of PySide6.QtCore.QFile

继承自： QTemporaryFile

概述#

方法#

静态函数#

注意

本文档可能包含从C++自动转换为Python的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细说明#

警告

本节包含从C++自动转换为Python的代码片段，可能包含错误。

QFile 是一个用于读取和写入文本和二进制文件的I/O设备以及 资源 。QFile 可以单独使用，或者更方便地与 QTextStream 或 QDataStream 一起使用。

文件名通常在构造函数中传递，但可以使用 setFileName() 在任何时间设置。《a class="reference internal" href="#PySide6.QtCore.QFile" title="PySide6.QtCore.QFile">QFile 预期文件分隔符为‘/’，无论操作系统如何。不支持使用其他分隔符（例如，‘\’）。

您可以使用 exists() 检查文件是否存在，并使用 remove() 删除文件。（更高级的文件系统相关操作由 QFileInfo 和 QDir 提供。）

文件使用 open() 打开，使用 close() 关闭，并使用 flush() 刷新。数据通常使用 QDataStream 或 QTextStream 读取和写入，但你也可以调用继承自 QIODevice 的函数 read()、readLine()、readAll() 和 write()。此外，QFile 还继承了 getChar()、putChar() 和 ungetChar() 方法，这些方法逐字符工作。

文件的大小通过 size() 返回。你可以用 pos() 获取当前文件位置，或使用 seek() 移动到新的文件位置。如果你已到达文件末尾，atEnd() 返回 true。

直接读取文件#

以下示例逐行读取文本文件

file = QFile("in.txt")
if not file.open(QIODevice.ReadOnly | QIODevice.Text):
    return
while not file.atEnd():
    line = file.readLine()
    process_line(line)

传递给 open() 的 QIODevice::Text 标志告诉 Qt 将 Windows 风格的行终止符（”\r\n”）转换为 C++ 风格的终止符（”\n”）。默认情况下，QFile 假设为二进制，即它不会对文件中存储的字节进行任何转换。

使用流读取文件#

下一个示例使用 QTextStream 逐行读取文本文件

file = QFile("in.txt")
if not file.open(QIODevice.ReadOnly | QIODevice.Text):
    return
in = QTextStream(file)
while not in.atEnd():
    line = in.readLine()
    process_line(line)

QTextStream 会负责将磁盘上存储的 8 位数据转换为 16 位 Unicode QString。默认情况下，它假设文件以 UTF-8 编码。这可以通过使用 setEncoding() 来更改。

要写入文本，我们可以使用操作符 <<()，该操作符被重载以接受左边的 QTextStream 和各种数据类型（包括 QString ）在右边

file = QFile("out.txt")
if not file.open(QIODevice.WriteOnly | QIODevice.Text):
    return
out = QTextStream(file)
out << "The magic number is: " << 49 << "\n"

与QDataStream相似，您可以使用操作符««()来写入数据，使用操作符»»()来读取数据。有关详细信息，请参阅类文档。

信号#

与QTcpSocket等其他QIODevice实现不同，QFile不会发出aboutToClose()、bytesWritten()或readyRead()信号。这个实现细节意味着QFile不适用于读取和写入某些类型的文件，例如Unix平台的设备文件。

平台特定问题#

Qt与I/O相关的API使用基于UTF-16的QString表示文件路径。但是，标准C++ API（如<cstdio>或<iostream>）或平台特定API通常需要一个8位编码的路径。您可以使用encodeName()和decodeName()在两种表示之间进行转换。

在Unix上，有一些特殊系统文件（例如在/proc中），对于这些文件，size()总是返回0，但您仍然可以从这样的文件中读取更多的数据；数据是直接响应您调用read()时生成的。然而，在这种情况下，您不能使用atEnd()来确定是否还有更多数据可以读取（因为atEnd()对于声明具有大小为0的文件将返回true）。相反，您应该调用readAll()，或者多次调用read()或readLine()，直到无法读取更多数据。下面的示例使用QTextStream逐行读取/proc/modules。

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()

在Unix-like系统和Windows中处理文件权限的方法不同。在Unix-like系统的非可写目录上，无法创建文件。在Windows中，情况并不总是如此，例如，通常无法写入的“我的文档”目录仍然可以在此目录中创建文件。

Qt对文件权限的理解有限，这尤其影响了setPermissions() 函数。在Windows上，Qt仅设置传统的只读标志，并且只有在没有写入标志传递时才会设置。Qt不操作访问控制列表（ACL），这使得此功能对于NTFS卷来说基本无用。它可能仍然适用于使用VFAT文件系统的USB闪存驱动器。也不会操作POSIX ACL。

在Android上，处理内容URI 时存在一些限制。

另请参阅

QTextStream QDataStream QFileInfo QDir The Qt Resource System

__init__(parent)#
参数:

parent – QObject

使用指定的parent构建一个新的文件对象。

__init__(name)
参数:

name – str

构建一个新的文件对象来表示具有给定name的文件。

注意

在包括Qt 6.8及之前的版本中，此构造函数是隐式的，作为向后兼容。从Qt 6.9开始，此构造函数无条件地指定为显式。用户可以通过在包含任何Qt头文件之前定义QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH宏来强制在早期版本的Qt中为此构造函数指定显式。

__init__(name, parent)
参数:

使用指定的 name 和给定的 parent 构造一个新的文件对象。

__init__()

构造一个 QFile 对象。

static copy(fileName, newName)#
参数:

  • fileName – str

  • newName – str

返回类型:

bool

这是一个重载函数。

将名为 fileName 的文件复制到 newName。

在复制之前，此文件会关闭。

如果复制的文件是符号链接（symlink），则复制引用的文件，而不是该链接本身。除了权限之外（权限也会被复制），不会复制其他文件元数据。

如果成功，则返回 true；否则返回 false。

注意，如果存在一个名为 newName 的文件，则 copy() 返回 false。这意味着 QFile 不会覆盖它。

注意

在 Android 上，此操作目前不支持 content 方案 URI。

另请参阅

rename()

copy(newName)
参数:

newName – str

返回类型:

bool

将名为 fileName() 的文件复制到 newName。

在复制之前，此文件会关闭。

如果复制的文件是符号链接（symlink），则复制引用的文件，而不是该链接本身。除了权限之外（权限也会被复制），不会复制其他文件元数据。

如果成功，则返回 true；否则返回 false。

注意，如果存在一个名为 newName 的文件，则 QFile 的 copy() 返回 false。这意味着 QFile 不会覆盖它。

注意

在 Android 上，此操作目前不支持 content 方案 URI。

另请参阅

setFileName()

static decodeName(localFileName)#
参数:

localFileName – QByteArray

返回类型:

str

使用 localFileName 进行与 encodeName() 相反的操作。

另请参阅

encodeName()

static decodeName(localFileName)
参数:

localFileName – str

返回类型:

str

这是一个重载函数。

返回给定 localFileName 的 Unicode 版本。有关详细信息，请参见 encodeName()。

静态encodeName(fileName)#
参数:

fileName – str

返回类型:

QByteArray

将 fileName 转换为可用于本地 API 的 8 位编码。在 Windows 上，该编码是活动 Windows（ANSI）代码页编码。在其他平台上，此编码为 UTF-8，对于 macOS 为分解形式（NFD）。

另请参阅

decodeName()

exists()#
返回类型:

bool

这是一个重载函数。

如果由 fileName() 指定的文件存在，则返回 true；否则返回 false。

另请参阅

fileName() setFileName()

静态exists(fileName)
参数:

fileName – str

返回类型:

bool

如果由 fileName 指定的文件存在，则返回 true；否则返回 false。

注意

如果 fileName 是指向不存在的文件的符号链接，则返回 false。

参数:

  • fileName – str

  • newName – str

返回类型:

bool

这是一个重载函数。

创建一个名为 linkName 的链接，指向文件 fileName。链接是什么取决于底层文件系统（无论是在 Windows 上的快捷方式还是在 Unix 上的符号链接）。如果成功，则返回 true；否则返回 false。

另请参阅

link()

link(newName)
参数:

newName – str

返回类型:

bool

创建一个指向当前由 fileName() 指定的文件的名为 linkName 的链接。链接是什么取决于底层文件系统（无论是在 Windows 上的快捷方式还是在 Unix 上的符号链接）。如果成功，则返回 true；否则返回 false。

此函数不会覆盖文件系统中已存在的实体；在这种情况下，link() 将返回 false 并将 error() 设置为返回 RenameError。

注意

要创建 Windows 上的有效链接，linkName 必须有 .lnk 文件扩展名。

另请参阅

setFileName()

moveToTrash()#
返回类型:

bool

将 fileName() 指定的文件移动到垃圾桶。成功时返回 true，并将 fileName() 设置为文件在垃圾桶中的路径；否则返回 false。

此函数的运行时间与被移动到垃圾箱的文件大小无关。如果对目录调用此函数，运行时间可能与被移动的文件数量成正比。

此函数使用 Windows 和 macOS 的 API 在这两个操作系统上执行垃圾箱操作。在其他地方（Unix 系统），此函数实现了 FreeDesktop.org 的垃圾箱规范版本 1.0。

注意

在使用 FreeDesktop.org 的垃圾箱实现时，如果不能通过文件重命名和硬链接将文件移动到垃圾箱位置，则该函数将失败。这种情况发生在要移动的文件位于当前用户没有权限在 .Trash 目录中创建的卷（挂载点）上，或者在一些不寻常的文件系统类型或配置中（例如不是挂载点的子卷）。

注意

在系统 API 不报告垃圾箱中文件位置的系统中，一旦文件被移动，fileName() 将被设置为空字符串。在没有垃圾桶的系统中，此函数总是返回 false。

静态 moveToTrash(fileName[, pathInTrash=None])
参数:

  • fileName – str

  • pathInTrash – 字符串

返回类型:

bool

这是一个重载函数。

将 fileName() 指定的文件移动到垃圾桶。成功时返回 true，并将提供的 pathInTrash（如果提供）设置为文件在垃圾桶中的路径；否则返回 false。

此函数的运行时间与被移动到垃圾箱的文件大小无关。如果对目录调用此函数，运行时间可能与被移动的文件数量成正比。

此函数使用 Windows 和 macOS 的 API 在这两个操作系统上执行垃圾箱操作。在其他地方（Unix 系统），此函数实现了 FreeDesktop.org 的垃圾箱规范版本 1.0。

注意

在使用 FreeDesktop.org 的垃圾箱实现时，如果不能通过文件重命名和硬链接将文件移动到垃圾箱位置，则该函数将失败。这种情况发生在要移动的文件位于当前用户没有权限在 .Trash 目录中创建的卷（挂载点）上，或者在一些不寻常的文件系统类型或配置中（例如不是挂载点的子卷）。

注意

在系统 API 不报告垃圾箱中文件路径的系统中，一旦文件被移动，pathInTrash 将被设置为空字符串。在没有垃圾桶的系统中，此函数总是返回 false。

open(flags, permissions)#
参数:
返回类型:

bool

这是一个重载函数。

如果文件不存在，并且 mode 暗示创建它，则将使用指定的 permissions 创建文件。

在 POSIX 系统中，实际权限受 umask 值的影响。

在Windows中，权限是通过ACLs来模拟的。当群组被授予比其他群组更少权限时，这些ACLs可能处于非规范顺序。具有此类权限的文件和目录在打开属性对话框的安全选项卡时将生成警告。授予群组与其他群组相同的所有权限可以避免此类警告。

另请参阅

OpenMode setFileName()

open(fd, ioFlags[, handleFlags=QFileDevice.FileHandleFlag.DontCloseHandle])
参数:
返回类型:

bool

这是一个重载函数。

以给定的 mode 打开现有的文件描述符 fd。可以使用 handleFlags 指定附加选项。如果成功，则返回 true；否则返回 false。

当使用此函数通过 QFile 打开文件时，close() 的行为由 AutoCloseHandle 标志控制。如果指定了 AutoCloseHandle 并此函数成功，那么调用 close() 将关闭所采用的句柄。否则，close() 实际上不会关闭文件，但只会刷新它。

警告

如果 fd 不是一个普通文件，例如，它是0（标准输入）、1（标准输出）或2（标准错误），则可能无法执行 seek() 操作。在这些情况下，size() 返回 0。有关更多信息，请参阅 isSequential()。

警告

由于此函数打开文件时未指定文件名，因此您无法使用此 QFile 与 QFileInfo 一起使用。

另请参阅

close()

static permissions(filename)#
参数:

filename – str

返回类型:

组合Permission

这是一个重载函数。

返回名为 fileName 的 QFile::Permission 的完整 OR 组合。

返回类型:

bool

通过

在删除前文件将被关闭。

另请参阅

setFileName()

参数:

fileName – str

返回类型:

bool

这是一个重载函数。

通过提供的

如果成功，则返回 true；否则返回 false。

另请参阅

remove()

参数:

newName – str

返回类型:

bool

将当前通过

如果已存在同名文件，rename() 返回

在重命名前文件将被关闭。

如果重命名操作失败，Qt 将尝试将此文件的全部内容复制到

另请参阅

setFileName()

参数:

  • oldName – str

  • newName – str

返回类型:

bool

这是一个重载函数。

将文件

如果已存在同名文件，

参数:

  • filename – str

  • sz – int

返回类型:

bool

这是一个重载函数。

将

警告

如果文件不存在，该函数可能会失败。

另请参阅

resize()

setFileName(name)#
参数:

name – str

警告

本节包含从C++自动转换为Python的代码片段，可能包含错误。

设置文件的name。名称可以不带路径、相对路径或绝对路径。

如果文件已经打开，请不要调用此函数。

如果文件名没有路径或相对路径，使用的路径将是应用在open() ** 调用时的当前目录路径。

示例

file = QFile()
QDir.setCurrent("/tmp")
file.setFileName("readme.txt")
QDir.setCurrent("/home")
file.open(QIODevice.ReadOnly) # opens "/home/readme.txt" under Unix

请注意，Qt 支持的所有操作系统上，目录分隔符“/”都起作用。

另请参阅

fileName() QFileInfo QDir

static setPermissions(filename, permissionSpec)#
参数:

  • filename – str

  • permissionSpec - Permission 的组合

返回类型:

bool

这是一个重载函数。

将 fileName 文件的权限设置为 permissions

symLinkTarget()#
返回类型:

str

这是一个重载函数。

返回符号链接（或Windows上的快捷方式）指向的文件或目录的绝对路径，或者如果对象不是符号链接，则返回一个空字符串。

此名称可能不一定表示一个现有文件；它只是一个字符串。如果符号链接指向一个现有文件，则 exists() 返回 true。

另请参阅

fileName() setFileName()

static symLinkTarget(fileName)
参数:

fileName – str

返回类型:

str

返回由 fileName 指定的符号链接（或Windows上的快捷方式）指向的文件或目录的绝对路径，如果 fileName 不对应符号链接，则返回空字符串。

此名称可能不一定表示一个现有文件；它只是一个字符串。如果符号链接指向一个现有文件，则 exists() 返回 true。