class QCommandLineParser

QCommandLineParser类提供了一种处理命令行选项的方法。更多…

概述

方法

• def __init__()

• def addHelpOption()

• def addOption()

• def addOptions()

• def addPositionalArgument()

• def addVersionOption()

• def applicationDescription()

• def clearPositionalArguments()

• def errorText()

• def helpText()

• 定义 isSet()

• 定义 optionNames()

• 定义 parse()

• 定义 positionalArguments()

• 定义 process()

• 定义 setApplicationDescription()

• 定义 setOptionsAfterPositionalArgumentsMode()

• 定义 setSingleDashWordOptionMode()

• 定义 showHelp()

• 定义 showVersion()

• 定义 unknownOptionNames()

• 定义 value()

• 定义 values()

注意

此文档可能包含了一些从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对代码片段翻译的贡献。如果发现翻译有问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 创建票据的方式来通知我们。

详细描述

警告

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

QCoreApplication 将命令行参数作为一个简单的字符串列表提供。 QCommandLineParser 提供了定义一组选项、解析命令行参数以及存储哪些选项实际上已被使用以及选项值的可能性。

任何不是选项（即不以 - 开头）的参数都存储为“位置参数”。

解析器处理短名称、长名称、同一选项数个名称以及选项值。

命令行中的选项以一个或两个《code class="docutils literal notranslate">-《预缩进字符开始 recognizing，后跟选项名称。选项《code class="docutils literal notranslate">-（单个短横线）是一个特殊情况，通常表示标准输入，并且不作为选项处理。解析器会将《code class="docutils literal notranslate">--（双短横线）后的所有内容视为位置参数。

短选项由单个字母组成。指定选项《code class="docutils literal notranslate">v（v）需要在命令行上传递《code class="docutils literal notranslate">-v。《在默认解析模式下，短选项可以写成紧凑形式，例如《code class="docutils literal notranslate">-abc《相当于《code class="docutils literal notranslate">-a -b -c《。可以通过更改解析模式为《code class="xref py py-attr docutils literal notranslate">ParseAsLongOptions《ParseAsLongOptions《来更改解析模式，在这种情况下，《code class="docutils literal notranslate">-abc《将被解析为长选项《code class="docutils literal notranslate">abc《。

长选项的长度超过一个字母，不能组合在一起。长选项《code class="docutils literal notranslate">verbose《将以《code class="docutils literal notranslate">--verbose《或《code class="docutils literal notranslate">-verbose《传递。

可以通过使用赋值运算符（《code class="docutils literal notranslate">-v=value《，--verbose=value《），或者使用空格（《code class="docutils literal notranslate">-v value《，--verbose value《）来向选项传递值。即使值以短横线开头，这也有效。

解析器不支持可选值 - 如果一个选项被设置为需要值，则必须存在该值。如果这样的选项放在最后且没有值，则该选项将被视为未指定。

解析器不自动支持使用格式《code class="docutils literal notranslate">--disable-option《或《code class="docutils literal notranslate">--no-option《来取消或禁用长选项。然而，可以通过将“no-option”作为选项名称之一来显式处理这种情况，并显式处理选项。

示例

if __name__ == "__main__":

    app = QCoreApplication(argc, argv)
    QCoreApplication.setApplicationName("my-copy-program")
    QCoreApplication.setApplicationVersion("1.0")
    parser = QCommandLineParser()
    parser.setApplicationDescription("Test helper")
    parser.addHelpOption()
    parser.addVersionOption()
    parser.addPositionalArgument("source", QCoreApplication.translate("main", "Source file to copy."))
    parser.addPositionalArgument("destination", QCoreApplication.translate("main", "Destination directory."))
    # A boolean option with a single name (-p)
    showProgressOption = QCommandLineOption("p", QCoreApplication.translate("main", "Show progress during copy"))
    parser.addOption(showProgressOption)
    # A boolean option with multiple names (-f, --force)
    QCommandLineOption forceOption(QStringList() << "f" << "force",
            QCoreApplication.translate("main", "Overwrite existing files."))
    parser.addOption(forceOption)
    # An option with a value
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
            QCoreApplication.translate("main", "Copy all source files into <directory>."),
            QCoreApplication.translate("main", "directory"))
    parser.addOption(targetDirectoryOption)
    # Process the actual command line arguments given by the user
    parser.process(app)
    args = parser.positionalArguments()
    # source is args.at(0), destination is args.at(1)
    showProgress = parser.isSet(showProgressOption)
    force = parser.isSet(forceOption)
    targetDir = parser.value(targetDirectoryOption)
    # ...

在上面的示例中，三个《code class="xref py py-meth docutils literal notranslate">addOption()《调用可以通过使用《code class="xref py py-meth docutils literal notranslate">addOptions()《来更加紧凑。

parser.addOptions({
    # A boolean option with a single name (-p)
    {"p",
        QCoreApplication.translate("main", "Show progress during copy")},
    # A boolean option with multiple names (-f, --force)
    {{"f", "force"},
        QCoreApplication.translate("main", "Overwrite existing files.")},
    # An option with a value
    {{"t", "target-directory"},
        QCoreApplication.translate("main", "Copy all source files into <directory>."),
        QCoreApplication.translate("main", "directory")},
})

已知的限制：在 QCoreApplication 和其子类中解析 Qt 选项发生在 QCommandLineParser 存在之前，所以它无法考虑。这意味着任何看起来像是内置 Qt 选项的选项值都会被 QCoreApplication 作为内置 Qt 选项处理。示例：--profile -reverse 将导致 QGuiApplication 看到设置了 -reverse 选项，并在 QCommandLineParser 定义 profile 选项并解析命令行之前从 arguments() 中删除。

如何在复杂应用程序中使用 QCommandLineParser

在实际应用中，需要对位置参数和选项值进行额外的错误检查。例如，应该检查数字的范围。

在此之后，建议引入一个函数来执行命令行解析，该函数接收包含选项值的结构体或类，并返回表示结果的模型。QtNetwork 模块的 dnslookup 示例说明了这一点。

class DnsQuery():

    DnsQuery() : type(QDnsLookup.A) {}
    QDnsLookup.Type type
    nameServer = QHostAddress()
    name = QString()
class CommandLineParseResult():

    enum class Status {
        Ok,
        Error,
        VersionRequested,
        HelpRequested

    statusCode = Status::Ok()
    std.optional<QString> errorString = std.nullopt

def parseCommandLine(parser,query):

    Status = CommandLineParseResult::Status()
    parser.setSingleDashWordOptionMode(QCommandLineParser.ParseAsLongOptions)
    nameServerOption = QCommandLineOption("n", "The name server to use.", "nameserver")
    parser.addOption(nameServerOption)
    typeOption = QCommandLineOption("t", "The lookup type.", "type")
    parser.addOption(typeOption)
    parser.addPositionalArgument("name", "The name to look up.")
    helpOption = parser.addHelpOption()
    versionOption = parser.addVersionOption()
    if not parser.parse(QCoreApplication.arguments()):
        return { Status.Error, parser.errorText() }
    if parser.isSet(versionOption):
        return { Status.VersionRequested }
    if parser.isSet(helpOption):
        return { Status.HelpRequested }
    if parser.isSet(nameServerOption):
        nameserver = parser.value(nameServerOption)
        query.nameServer = QHostAddress(nameserver)
        if (query.nameServer.isNull()
            or query.nameServer.protocol() == QAbstractSocket.UnknownNetworkLayerProtocol) {
            return { Status.Error,
                     "Bad nameserver address: %1".arg(nameserver) }


    if parser.isSet(typeOption):
        typeParameter = parser.value(typeOption)
        if std.optional<QDnsLookup.Type> type = typeFromParameter(typeParameter):
            query.type = type
else:
            return { Status.Error, "Bad record type: %1".arg(typeParameter) }

    positionalArguments = parser.positionalArguments()
    if positionalArguments.isEmpty():
        return { Status.Error, "Argument 'name' missing." }
    if positionalArguments.size() > 1:
        return { Status.Error, "Several 'name' arguments specified." }
    query.name = positionalArguments.first()
    return { Status.Ok }

在主函数中，如果传递了帮助选项，应将帮助信息打印到标准输出，并且应用程序应返回退出代码 0。

如果检测到错误，应将错误信息打印到标准错误输出，并且应用程序应返回非 0 的退出代码。

QCoreApplication.setApplicationVersion(QT_VERSION_STR)
QCoreApplication.setApplicationName(QCoreApplication.translate("QDnsLookupExample",
                                                                 "DNS Lookup Example"))
parser = QCommandLineParser()
parser.setApplicationDescription(QCoreApplication.translate("QDnsLookupExample",
                                                             "An example demonstrating the "
                                                             "class QDnsLookup."))
query = DnsQuery()
Status = CommandLineParseResult::Status()
parseResult = parseCommandLine(parser, query)

if parseResult.statusCode == Status.Ok:
    break
elif parseResult.statusCode == Status.Error:
    std::fputs(qPrintable(parseResult.errorString.value_or("Unknown error occurred")),
               stderr)
    std::fputs("\n\n", stderr)
    std::fputs(qPrintable(parser.helpText()), stderr)
    return 1
elif parseResult.statusCode == Status.VersionRequested:
    parser.showVersion()
    Q_UNREACHABLE_RETURN(0)
elif parseResult.statusCode == Status.HelpRequested:
    parser.showHelp()
    Q_UNREACHABLE_RETURN(0)

需要考虑的一个特殊情况是 Windows 和移动平台上的 GUI 应用程序。这些应用程序可能不会使用标准输出或错误通道，因为输出要么被丢弃，要么不可访问。

在 Windows 上，如果无法获取控制台窗口，QCommandLineParser 使用消息框来显示使用信息和错误。

对于其他平台，建议使用 QMessageBox 显示帮助文本和错误信息。为了保留帮助文本的格式，应使用具有 <pre> 元素的富文本。

switch (parseResult.statusCode) {
case Status::Ok:
    break;
case Status::Error: {
    QString errorMessage = parseResult.errorString.value_or(u"Unknown error occurred"_qs);
    QMessageBox::warning(0, QGuiApplication::applicationDisplayName(),
                         "<html><head/><body><h2>" + errorMessage + "</h2><pre>"
                         + parser.helpText() + "</pre></body></html>");
    return 1;
}
case Status::VersionRequested:
    QMessageBox::information(0, QGuiApplication::applicationDisplayName(),
                             QGuiApplication::applicationDisplayName() + ' '
                             + QCoreApplication::applicationVersion());
    return 0;
case Status::HelpRequested:
    QMessageBox::warning(0, QGuiApplication::applicationDisplayName(),
                         "<html><head/><body><pre>"
                         + parser.helpText() + "</pre></body></html>");
    return 0;
}

但是，这一点不适用于 dnslookup 示例，因为它是一个控制台应用程序。

另请参阅

QCommandLineOption QCoreApplication

class SingleDashWordOptionMode

这个枚举描述了解析器如何诠释以单短横线后跟多个字母开头的命令行选项，如-abc。

常量	描述
QCommandLineParser.ParseAsCompactedShortOptions	-abc 被解释为 -a -b -c，即作为三个紧凑的选项出现在命令行中，如果这些选项都没有带值。如果 a 有带值，则它被解释为 -a bc，即短选项 a 后跟值 bc。这在工具（如编译器）中通常被用来处理如 -DDEFINE=VALUE 或 -I/include/path 这样的选项。这是默认解析模式。建议新应用使用这种模式。
QCommandLineParser.ParseAsLongOptions	-abc 被解释为 --abc，即作为名为 abc 的长选项。这是 Qt 自身工具（如 uic、rcc 等）一直用来解析参数的方式。这种模式应该用于保持那些以这种方式解析参数的应用的兼容性。如果 a 选项设置了 ShortOptionStyle 标志，则它仍然被解释为 -a bc。

另请参阅

setSingleDashWordOptionMode()

class OptionsAfterPositionalArgumentsMode

此枚举描述了解析器解释出现在位置参数之后的选项的方式。

常量	描述
QCommandLineParser.ParseAsOptions	application argument --opt -t 被解释为设置选项 opt 和 t，这与 application --opt -t argument 的做法一样。这是默认解析模式。为了指定 --opt 和 -t 是位置参数，用户可以使用 --，如 application argument -- --opt -t。
QCommandLineParser.ParseAsPositionalArguments	application argument --opt 被解释为有两个位置参数，argument 和 --opt。这种模式对于旨在启动其他可执行文件（例如，包装器、调试工具等）或支持内部命令后跟命令选项的可执行文件很有用。argument 是命令的名称，并且所有在它之后出现的选项都可以由另一个命令行解析器收集和解析，可能是在另一个可执行文件中。

另请参阅

setOptionsAfterPositionalArgumentsMode()

__init__()

构造一个命令行解析器对象。

addHelpOption()

返回类型：:

QCommandLineOption

警告

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

将帮助选项添加到命令行解析器。

为本命令行指定的选项由-h或--help描述。在Windows上，也支持替代的-?。选项--help-all扩展了此功能，以包括由本命令定义之外的一般Qt选项，并将它们包括在输出中。

这些选项将由QCommandLineParser自动处理。

请记住使用setApplicationDescription()来设置应用程序描述，当使用此选项时，它将被显示。

示例

if __name__ == "__main__":

    app = QCoreApplication(argc, argv)
    QCoreApplication.setApplicationName("my-copy-program")
    QCoreApplication.setApplicationVersion("1.0")
    parser = QCommandLineParser()
    parser.setApplicationDescription("Test helper")
    parser.addHelpOption()
    parser.addVersionOption()
    parser.addPositionalArgument("source", QCoreApplication.translate("main", "Source file to copy."))
    parser.addPositionalArgument("destination", QCoreApplication.translate("main", "Destination directory."))
    # A boolean option with a single name (-p)
    showProgressOption = QCommandLineOption("p", QCoreApplication.translate("main", "Show progress during copy"))
    parser.addOption(showProgressOption)
    # A boolean option with multiple names (-f, --force)
    QCommandLineOption forceOption(QStringList() << "f" << "force",
            QCoreApplication.translate("main", "Overwrite existing files."))
    parser.addOption(forceOption)
    # An option with a value
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
            QCoreApplication.translate("main", "Copy all source files into <directory>."),
            QCoreApplication.translate("main", "directory"))
    parser.addOption(targetDirectoryOption)
    # Process the actual command line arguments given by the user
    parser.process(app)
    args = parser.positionalArguments()
    # source is args.at(0), destination is args.at(1)
    showProgress = parser.isSet(showProgressOption)
    force = parser.isSet(forceOption)
    targetDir = parser.value(targetDirectoryOption)
    # ...

返回选项实例，该实例可用于调用isSet()。

addOption(commandLineOption)

参数：

commandLineOption – QCommandLineOption

返回类型：:

bool

将选项option添加到解析时查找的选项中。

如果添加选项成功返回true，否则返回false。

如果选项没有关联名称，或者选项的名称与前一个添加的选项名称冲突，则添加选项会失败。

addOptions(options)

参数：

options – QCommandLineOption列表

返回类型：:

bool

将选项添加到解析时查找的列表中。选项由参数options指定。

如果添加所有选项成功返回true，否则返回false。

有关此函数可能失败的情况，请参阅addOption()的文档。

addPositionalArgument(name, description[, syntax=""])

参数：

• name – str

• description – str

• syntax – str

警告

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

为帮助文本定义应用额外的参数。

参数name和description将显示在帮助中的`Arguments:`部分。如果指定了`syntax`，它将被添加到用法行中，否则将添加`name`。

示例

# Usage: image-editor file
#
# Arguments:
#   file                  The file to open.
parser.addPositionalArgument("file", QCoreApplication.translate("main", "The file to open."))
# Usage: web-browser [urls...]
#
# Arguments:
#   urls                URLs to open, optionally.
parser.addPositionalArgument("urls", QCoreApplication.translate("main", "URLs to open, optionally."), "[urls...]")
# Usage: cp source destination
#
# Arguments:
#   source                Source file to copy.
#   destination           Destination directory.
parser.addPositionalArgument("source", QCoreApplication.translate("main", "Source file to copy."))
parser.addPositionalArgument("destination", QCoreApplication.translate("main", "Destination directory."))

另请参阅

addHelpOption() helpText()

addVersionOption()

返回类型：:

QCommandLineOption

添加 -v / --version 选项，用于显示应用程序的版本字符串。

此选项由 QCommandLineParser 自动处理。

您可以通过使用 setApplicationVersion()设置实际版本字符串。

返回选项实例，该实例可用于调用isSet()。

applicationDescription()

返回类型：:

str

返回在 setApplicationDescription()中设置的应用程序描述。

另请参阅

setApplicationDescription()

clearPositionalArguments()

警告

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

清除帮助文本中对额外参数的定义。

这对于支持带不同选项的多个命令的特殊工具是必要的。一旦确定了实际命令，就可以为该命令定义选项，并相应地调整命令的帮助文本。

示例

app = QCoreApplication(argc, argv)
parser = QCommandLineParser()
parser.addPositionalArgument("command", "The command to execute.")
# Call parse() to find out the positional arguments.
parser.parse(QCoreApplication.arguments())
args = parser.positionalArguments()
command = args.isEmpty() if QString() else args.first()
if command == "resize":
    parser.clearPositionalArguments()
    parser.addPositionalArgument("resize", "Resize the object to a size().", "resize [resize_options]")
    parser.addOption(QCommandLineOption("size", "New size.", "new_size"))
    parser.process(app)
    # ...

/*
This code results in context-dependent help:
$ tool --help
Usage: tool command
Arguments:
  command The command to execute.
$ tool resize --help
Usage: tool resize [resize_options]
Options:
  size <size> New size. = size <size> New size. - 1
Arguments:
  resize Resize the object to a size().
*/

errorText()

返回类型：:

str

返回针对用户的翻译错误文本。只有在parse()返回false时，才应调用该函数。

helpText()

返回类型：:

str

返回包含完整帮助信息的字符串。

另请参阅

showHelp()

isSet(option)

参数：

option – QCommandLineOption

返回类型：:

bool

警告

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

这是一个重载函数。

检查是否将 option 传递给了应用程序。

如果设置了 option，则返回 true，否则返回 false。

这是检查无值的选项的首选方法。

示例

app = QCoreApplication(argc, argv)
parser = QCommandLineParser()
verboseOption = QCommandLineOption("verbose")
parser.addOption(verboseOption)
parser.process(app)
verbose = parser.isSet(verboseOption)

isSet(name)

参数：

name – str

返回类型：:

bool

警告

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

检查是否向应用程序传递了 name 选项。

如果设置了 name 选项，则返回 true，否则返回 false。

提供的名称可以是使用 addOption() 添加的任何长或短选项名称。所有选项名称都被视为等效。如果名称不被识别或该选项不存在，则返回 false。

示例

verbose = parser.isSet("verbose")

optionNames()

返回类型：:

字符串列表

返回找到的选项名称列表。

此方法返回解析器找到的所有已知选项名称的列表，按照它们被找到的顺序。对于形式为 {–option=value} 的长选项，将省略值部分。

此列表中的名称不包括前面的横杠字符。如果解析器多次遇到某个名称，则该名称在此列表中可能多次出现。

可以使用 value() 或 values() 与列表中的任何条目一起使用，以获取任何相关的选项值。

parse(arguments)

参数：

arguments – 字符串列表

返回类型：:

bool

解析命令行 arguments。

大多数程序都不需要调用此方法，只需调用一次 process() 即可。

parse() 是更底层的，只执行解析。应用程序将必须使用 errorText() 来处理错误，如果 parse() 返回 false。这可以在图形程序中显示图形错误信息时很有用。

调用 parse() 而不是 process() 也可以很有用，以便暂时忽略未知选项，因为稍后（根据其中一个参数）提供更多的选项定义之前，将调用 process() 。

别忘了，arguments 必须以可执行文件名称开始（虽然会被忽略）。

解析出错时（未知选项或缺失值）返回 false；否则返回 true。

另请参阅

process()

positionalArguments()

返回类型：:

字符串列表

返回位置参数列表。

这些都是没有被识别为选项的部分的所有参数。

process(app)

参数：

app – QCoreApplication

这是一个重载函数。

命令行来自 QCoreApplication 实例 app。

process(arguments)

参数：

arguments – 字符串列表

处理命令行 arguments。

除了解析选项（如 parse() ）外，此函数还处理内置选项和错误。

内置选项为 --version 如果调用过 addVersionOption ，以及 --help / --help-all 如果调用过 addHelpOption。

在调用这些选项之一或发生错误（例如传递了未知选项）时，当前进程将停止，使用 exit() 函数。

另请参阅

arguments() parse()

setApplicationDescription(description)

参数：

description – str

设置由 helpText() 显示的应用 description。

另请参阅

applicationDescription()

setOptionsAfterPositionalArgumentsMode(mode)

参数：

mode – OptionsAfterPositionalArgumentsMode

将解析模式设置为 parsingMode。必须在 process() 或 parse() 调用之前调用此函数。

setSingleDashWordOptionMode(parsingMode)

参数：

parsingMode – SingleDashWordOptionMode

设置解析模式为 singleDashWordOptionMode。这必须在调用 process() 或 parse() 之前完成。

showHelp([exitCode=0])

参数：

exitCode – int

显示帮助信息并退出应用程序。这由 –help 选项自动触发，但也可以在用户不正确调用应用程序时使用来显示帮助。退出代码设置为 exitCode。如果用户请求查看帮助，则应将其设置为 0，如果发生错误，则设置为任何其他值。

另请参阅

helpText()

showVersion()

显示 applicationVersion() 中的版本信息，并退出应用程序。这由 –version 选项自动触发，但也可用于在没有使用 process() 时显示版本。退出代码设置为 EXIT_SUCCESS (0)。

另请参阅

addVersionOption()

unknownOptionNames()

返回类型：:

字符串列表

返回未知选项名称的列表。

该列表将包括未识别的既长又短名称的选项。对于任何格式为 {–option=value} 的长选项，值部分将被删除，只添加长名称。

此列表中的名称不包括前面的横杠字符。如果解析器多次遇到某个名称，则该名称在此列表中可能多次出现。

另请参阅

optionNames()

value(option)

参数：

option – QCommandLineOption

返回类型：:

str

这是一个重载函数。

返回给定 option 的选项值，或如果未找到，则返回空字符串。

对于解析器找到的选项，返回该选项找到的最后一个值。如果命令行上未指定该选项，则返回默认值。

如果没有值，则返回空字符串。

另请参阅

values() setDefaultValue() setDefaultValues()

value(name)

参数：

name – str

返回类型：:

str

返回为给定选项名称 optionName 找到的选项值，如果未找到，则返回空字符串。

提供的名称可以是使用 addOption() 方法添加的任何选项的长或短名称。所有选项名称都被视为等效。如果不识别名称或该选项不存在，则返回空字符串。

对于解析器找到的选项，返回该选项找到的最后一个值。如果命令行上未指定该选项，则返回默认值。

如果选项不接受值，将打印警告，并返回空字符串。

另请参阅

values() setDefaultValue() setDefaultValues()

values(option)

参数：

option – QCommandLineOption

返回类型：:

字符串列表

这是一个重载函数。

返回为给定 option 找到的选项值的列表，如果未找到，则返回空列表。

对于解析器找到的选项，列表将为解析器遇到每个选项一次条目。如果未在命令行上指定选项，则返回默认值。

如果选项不接受值，则返回空列表。

另请参阅

value() setDefaultValue() setDefaultValues()

values(name)

参数：

name – str

返回类型：:

字符串列表

返回为给定选项名称 optionName 找到的选项值的列表，如果未找到，则返回空列表。

提供的名称可以是使用 addOption() 方法添加的任何选项的长或短名称。所有选项名称都被视为等效。如果不识别名称或该选项不存在，则返回空列表。

对于解析器找到的选项，列表将为解析器遇到每个选项一次条目。如果未在命令行上指定选项，则返回默认值。

如果选项不接受值，则返回空列表。

另请参阅

value() setDefaultValue() setDefaultValues()