PySide6.QtCore.QFile¶

class QFile¶

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

继承者： QTemporaryFile

概要¶

方法¶

def __init__()
def copy()
def exists()
def link()
def moveToTrash()
def open()
def remove()
def rename()
def setFileName()
def symLinkTarget()

静态函数¶

def copy()
def decodeName()
def encodeName()
def exists()
def link()
def moveToTrash()
def permissions()
def remove()
def rename()
def resize()
def setPermissions()
def symLinkTarget()

注意

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

详细描述¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

文件名通常在构造函数中传递，但可以随时使用setFileName()进行设置。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() 来更改。

要写入文本，我们可以使用operator<<()，它被重载以在左侧接受一个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 类似，您可以使用 operator<<() 来写入数据，并使用 operator>>() 来读取数据。详情请参阅类文档。

信号¶

与其他QIODevice实现（如QTcpSocket）不同，QFile不会发出aboutToClose()、bytesWritten()或readyRead()信号。这一实现细节意味着QFile不适合读写某些类型的文件，例如Unix平台上的设备文件。

平台特定问题¶

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

在Unix系统上，有一些特殊的系统文件（例如在/proc中），对于这些文件，size()将始终返回0，但你仍然可能能够从这样的文件中读取更多数据；这些数据是在你调用read()时直接生成的。然而，在这种情况下，你不能使用atEnd()来确定是否还有更多数据可读（因为对于声称大小为0的文件，atEnd()将返回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系统和Windows上的处理方式不同。在类Unix系统上的一个不可写目录中，无法创建文件。但在Windows上并不总是这样，例如，“我的文档”目录通常不可写，但仍然可以在其中创建文件。

Qt对文件权限的理解有限，这尤其影响了setPermissions()函数。在Windows上，Qt只会设置传统的只读标志，并且只有在没有传递任何Write*标志时才会设置。Qt不操作访问控制列表（ACLs），这使得该函数对于NTFS卷大多无用。它可能仍然对使用VFAT文件系统的USB闪存盘有用。POSIX ACLs也不被操作。

在Android上，处理内容URI时有一些限制：

可能需要通过提示用户使用QFileDialog来获取访问权限，该对话框实现了Android的原生文件选择器。

旨在遵循Scoped storage指南，例如使用应用程序特定目录而不是其他公共外部目录。有关更多信息，请参阅storage best practices。

由于Qt API的设计（例如QFile），无法将后者API与Android的MediaStore API完全集成。

另请参阅

QTextStream QDataStream QFileInfo QDir Qt资源系统

__init__()¶

构造一个QFile对象。

__init__(parent)

Parameters:: 父对象 – QObject

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

__init__(name)

Parameters:: name – str

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

注意

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

__init__(name, parent)

Parameters:

name – str
parent – QObject

使用给定的parent构造一个新的文件对象，以表示具有指定name的文件。

copy(newName)¶

Parameters:: newName – 字符串
Return type:: 布尔

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

此文件在复制之前已关闭。

如果复制的文件是一个符号链接（symlink），则复制的是它指向的文件，而不是链接本身。除了复制的权限外，不会复制其他文件元数据。

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

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

注意

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

另请参阅

setFileName()

static copy(fileName, newName)

Parameters:

fileName – str
newName – 字符串

Return type:

布尔

这是一个重载函数。

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

此文件在复制之前已关闭。

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

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

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

注意

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

另请参阅

rename()

static decodeName(localFileName)¶

Parameters:: localFileName – QByteArray
Return type:: 字符串

这与使用localFileName的encodeName()相反。

另请参阅

encodeName()

static decodeName(localFileName)

Parameters:: localFileName – str
Return type:: 字符串

这是一个重载函数。

返回给定localFileName的Unicode版本。详情请参见encodeName()。

static encodeName(fileName)¶

Parameters:: fileName – str
Return type:: QByteArray

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

另请参阅

decodeName()

exists()¶

Return type:: 布尔

这是一个重载函数。

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

另请参阅

fileName() setFileName()

static exists(fileName)

Parameters:: fileName – str
Return type:: 布尔

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

注意

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

link(newName)¶

Parameters:: newName – 字符串
Return type:: 布尔

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

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

注意

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

另请参阅

setFileName()

static link(fileName, newName)

Parameters:

fileName – str
newName – 字符串

Return type:

布尔

这是一个重载函数。

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

另请参阅

link()

moveToTrash()¶

Return type:: 布尔

将fileName()指定的文件移动到回收站。如果成功，返回true，并将fileName()设置为文件在回收站中的路径；否则返回false。

此函数的运行时间与被删除文件的大小无关。如果此函数在目录上调用，则可能与被删除的文件数量成正比。如果当前的fileName()指向一个符号链接，此函数将把链接移动到回收站，可能会破坏它，而不是链接的目标。

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

注意

当使用FreeDesktop.org的回收站实现时，如果无法通过文件重命名和硬链接将文件移动到回收站位置，此函数将失败。如果被删除的文件位于当前用户没有权限创建.Trash目录的卷（挂载点）上，或者某些不常见的文件系统类型或配置（例如本身不是挂载点的子卷），则会出现这种情况。

注意

在系统API不报告文件在回收站中的位置的系统上，一旦文件被移动，fileName()将被设置为空字符串。在没有回收站的系统上，此函数始终返回false。

static moveToTrash(fileName[, pathInTrash=None])

Parameters:

fileName – str
pathInTrash – str

Return type:

布尔

这是一个重载函数。

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

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

注意

当使用FreeDesktop.org的回收站实现时，如果无法通过文件重命名和硬链接将文件移动到回收站位置，此函数将失败。如果被删除的文件位于当前用户没有权限创建.Trash目录的卷（挂载点）上，或者某些不常见的文件系统类型或配置（如本身不是挂载点的子卷），则会出现这种情况。

注意

在系统API不报告文件在回收站中的路径的系统上，一旦文件被移动，pathInTrash将被设置为空字符串。在没有回收站的系统上，此函数始终返回false。

open(flags, permissions)¶

Parameters:

flags – OpenModeFlag 的组合
permissions – Permission 的组合

Return type:

布尔

这是一个重载函数。

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

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

在Windows上，权限是使用ACL模拟的。当组被授予的权限少于其他组时，这些ACL可能处于非规范顺序。当打开属性对话框的安全选项卡时，具有此类权限的文件和目录将生成警告。授予组所有授予给其他组的权限可以避免此类警告。

另请参阅

OpenMode setFileName() QT_USE_NODISCARD_FILE_OPEN

open(fd, ioFlags[, handleFlags=QFileDevice.FileHandleFlag.DontCloseHandle])

Parameters:

fd – int
ioFlags – OpenModeFlag 的组合
handleFlags – FileHandleFlag 的组合

Return type:

布尔

这是一个重载函数。

在给定的mode中打开现有的文件描述符fd。handleFlags可用于指定其他选项。如果成功，返回true；否则返回false。

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

警告

如果 fd 不是一个常规文件，例如它是 0 (stdin)、1 (stdout) 或 2 (stderr)，你可能无法使用 seek()。在这些情况下，size() 返回 0。更多信息请参见 isSequential()。

警告

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

另请参阅

close() QT_USE_NODISCARD_FILE_OPEN

static permissions(filename)¶

Parameters:: 文件名 – str
Return type:: Permission的组合

这是一个重载函数。

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

remove()¶

Return type:: 布尔

删除由fileName()指定的文件。如果成功，返回true；否则返回false。

文件在删除之前被关闭。

另请参阅

setFileName()

static remove(fileName)

Parameters:: fileName – str
Return type:: 布尔

这是一个重载函数。

移除由给定的fileName指定的文件。

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

另请参阅

remove()

rename(newName)¶

Parameters:: newName – 字符串
Return type:: 布尔

将当前由fileName()指定的文件重命名为newName。如果成功，则返回true；否则返回false。

如果已经存在一个名为newName的文件，rename()将返回false（即，QFile不会覆盖它）。

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

如果重命名操作失败，Qt 将尝试将此文件的内容复制到 newName，然后删除此文件，仅保留 newName。如果复制操作失败或无法删除此文件，目标文件 newName 将被删除以恢复旧状态。

另请参阅

setFileName()

static rename(oldName, newName)

Parameters:

oldName – str
newName – 字符串

Return type:

布尔

这是一个重载函数。

将文件 oldName 重命名为 newName。如果成功，返回 true；否则返回 false。

如果已经存在一个名为newName的文件，rename()将返回false（即，QFile不会覆盖它）。

另请参阅

rename()

static resize(filename, sz)¶

Parameters:

filename – str
sz – 整数

Return type:

布尔

这是一个重载函数。

将fileName设置为大小（以字节为单位）sz。如果调整大小成功，则返回true；否则返回false。如果sz大于fileName当前的大小，则新字节将设置为0；如果sz较小，则文件将被截断。

警告

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

另请参阅

resize()

setFileName(name)¶

Parameters:: 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)¶

Parameters:

filename – str
permissionSpec – Permission 的组合

Return type:

布尔

这是一个重载函数。

将fileName文件的权限设置为permissions。

symLinkTarget()¶

Return type:: 字符串

这是一个重载函数。

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

这个名称可能不代表一个实际存在的文件；它只是一个字符串。如果符号链接指向一个实际存在的文件，exists() 返回 true。

另请参阅

fileName() setFileName()

static symLinkTarget(fileName)

Parameters:: fileName – str
Return type:: 字符串

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

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