Python argparse 教程-工具盒子

我们经常需要在 Python 程序运行过程中获取命令行参数，argparse 模块是 Python 标准库中推荐的命令行解析模块，本文介绍相关用法。

sys.argv {#sys-argv}

Python内置的sys.argv保存了完整的参数列表，我们可以从中解析出需要的参数：

执行如下命令执行 python 脚本

输出：

这种方式能应付简单的参数，但参数稍微复杂点，比如可以使用-d复制目录，使用--filename *.py过滤文件名等，解析起来就非常麻烦。

为了简化参数解析，我们可以使用内置的argparse库，定义好各个参数类型后，它能直接返回有效的参数。

argparse {#argparse}

argparse 模块可以让人轻松编写用户友好的命令行接口。程序定义它需要的参数，然后 argparse 将弄清如何从 sys.argv 解析出那些参数。 argparse 模块还会自动生成帮助和使用手册，并在用户给程序传入无效参数时报出错误信息。

创建解析器 ArgumentParser {#创建解析器-ArgumentParser}

使用 argparse 的第一步是创建一个 ArgumentParser 对象：

ArgumentParser 对象包含将命令行解析成 Python 数据类型所需的全部信息。

创建一个新的 ArgumentParser 对象。所有的参数都应当作为关键字参数传入：

文档链接：https://docs.python.org/zh-cn/3.10/library/argparse.html#argparse.ArgumentParser

| 参数名称 | 描述 | |-----------------------|----------------------------------------------------| | prog | 程序的名称 (默认值: os.path.basename(sys.argv[0])) | | usage | 描述程序用途的字符串（默认值：从添加到解析器的参数生成） | | description | 要在参数帮助信息之前显示的文本（默认：无文本） | | epilog | 要在参数帮助信息之后显示的文本（默认：无文本） | | parents | 一个 ArgumentParser 对象的列表，它们的参数也应包含在内 | | formatter_class | 用于自定义帮助文档输出格式的类 | | prefix_chars | 可选参数的前缀字符集合（默认值： '-'） | | fromfile_prefix_chars | 当需要从文件中读取其他参数时，用于标识文件名的前缀字符集合（默认值： None） | | argument_default | 参数的全局默认值（默认值： None） | | conflict_handler | 解决冲突选项的策略（通常是不必要的） | | add_help | 为解析器添加一个 -h/--help 选项（默认值： True） | | allow_abbrev | 如果缩写是无歧义的，则允许缩写长选项（默认值：True） | | exit_on_error | 决定当错误发生时是否让 ArgumentParser 附带错误信息退出。 (默认值: True) |

在 3.5 版更改: 增加了 allow_abbrev 参数。

在 3.8 版更改: 在之前的版本中，allow_abbrev 还会禁用短旗标分组，例如 -vv 表示为 -v -v。

在 3.9 版更改: 添加了 exit_on_error 形参。

prog {#prog}

默认情况下，ArgumentParser 对象使用 sys.argv[0] 来确定如何在帮助消息中显示程序名称。这一默认值几乎总是可取的，因为它将使帮助消息与从命令行调用此程序的方式相匹配。

例如，对于有如下代码的名为 args.py 的文件：

调用 -h 参数：

输出信息中的 args.py 就是从 sys.argv[0] 中获取的。

如果需要修改这项内容，可以修改 prog 参数：

调用 -h 参数：

也可以用 parser.print_help() 来调用帮助信息：

输出信息：

无论是从 sys.argv[0] 或是从 prog= 参数确定的程序名称，都可以在帮助消息里通过 %(prog)s 格式说明符来引用。

输出信息：

usage {#usage}

默认情况下，ArgumentParser 根据它包含的参数来构建用法消息：

可以通过 usage= 关键字参数覆盖这一默认消息：

在用法消息中可以使用 %(prog)s 格式说明符来填入程序名称。

description {#description}

大多数对 ArgumentParser 构造方法的调用都会使用 description= 关键字参数。这个参数简要描述这个程序做什么以及怎么做。在帮助消息中，这个描述会显示在命令行用法字符串和各种参数的帮助消息之间:

在默认情况下，description 将被换行以便适应给定的空间。如果想改变这种行为，见 formatter_class 参数。

epilog {#epilog}

一些程序喜欢在 description 参数后显示额外的对程序的描述。这种文字能够通过给 ArgumentParser 提供 epilog= 参数而被指定。

和 description 参数一样，epilog= text 在默认情况下会换行，但是这种行为能够被调整通过提供 formatter_class 参数给 ArgumentParse.

parents {#parents}

有些时候，少数解析器会使用同一系列参数。单个解析器能够通过提供 parents= 参数给 ArgumentParser 而使用相同的参数而不是重复这些参数的定义。parents= 参数使用 ArgumentParser 对象的列表，从它们那里收集所有的位置和可选的行为，然后将这写行为加到正在构建的 ArgumentParser 对象。

请注意大多数父解析器会指定 add_help=False . 否则， ArgumentParse 将会看到两个 -h/--help 选项（一个在父参数中一个在子参数中）并且产生一个错误。

注解: 你在通过 parents= 传递解析器之前必须完全初始化它们。如果你在子解析器之后改变父解析器，这些改变将不会反映在子解析器上。

formatter_class {#formatter-class}

ArgumentParser 对象允许通过指定备用格式化类来自定义帮助格式。目前，有四种这样的类。

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter
class argparse.MetavarTypeHelpFormatter

RawDescriptionHelpFormatter 和 RawTextHelpFormatter 在正文的描述和展示上给与了更多的控制。ArgumentParser 对象会将 description 和 epilog 的文字在命令行中自动换行。

传 RawDescriptionHelpFormatter 给 formatter_class= 表示 description 和 epilog 已经被正确的格式化了，不能在命令行中被自动换行:

RawTextHelpFormatter 保留所有种类文字的空格，包括参数的描述。然而，多重的新行会被替换成一行。如果你想保留多重的空白行，可以在新行之间加空格。

ArgumentDefaultsHelpFormatter 自动添加默认的值的信息到每一个帮助信息的参数中:

MetavarTypeHelpFormatter 为它的值在每一个参数中使用 type 的参数名当作它的显示名（而不是使用通常的格式 dest ):

prefix_chars {#prefix-chars}

许多命令行会使用 - 当作前缀，比如 -f/--foo。如果解析器需要支持不同的或者额外的字符，比如像 +f 或者 /foo 的选项，可以在参数解析构建器中使用 prefix_chars= 参数。

prefix_chars= 参数默认使用 '-'。提供一组不包括 - 的字符将导致 -f/--foo 选项不被允许。

fromfile_prefix_chars {#fromfile-prefix-chars}

在某些时候，例如在处理一个特别长的参数列表的时候，把参数列表存入一个文件中而不是在命令行中打印出来会更有意义。如果提供 fromfile_prefix_chars= 参数给 ArgumentParser 构造器，则任何以指定字符打头的参数都将被当作文件来处理，并将被它们包含的参数所替代。

举例来说:

从文件读取的参数在默认情况下必须一个一行（但是可参见 convert_arg_line_to_args()）并且它们被视为与命令行上的原始文件引用参数位于同一位置。所以在以上例子中，['-f', 'foo', '@args.txt'] 的表示和 ['-f', 'foo', '-f', 'bar'] 的表示相同。

fromfile_prefix_chars= 参数默认为 None，意味着参数不会被当作文件对待。

argument_default {#argument-default}

一般情况下，参数默认会通过设置一个默认到 add_argument() 或者调用带一组指定键值对的 ArgumentParser.set_defaults() 方法。但是有些时候，为参数指定一个普遍适用的解析器会更有用。这能够通过传输 argument_default= 关键词参数给 ArgumentParser 来完成。举个栗子，要全局禁止在 parse_args() 中创建属性，我们提供 argument_default=SUPPRESS:

allow_abbrev {#allow-abbrev}

正常情况下，当你向 ArgumentParser 的 parse_args() 方法传入一个参数列表时，它会 recognizes abbreviations。

这个特性可以设置 allow_abbrev 为 False 来关闭:

3.5 新版功能.

conflict_handler {#conflict-handler}

ArgumentParser 对象不允许在相同选项字符串下有两种行为。默认情况下， ArgumentParser 对象会产生一个异常如果去创建一个正在使用的选项字符串参数。

>>>

有些时候（例如：使用 parents），重写旧的有相同选项字符串的参数会更有用。为了产生这种行为， 'resolve' 值可以提供给 ArgumentParser 的 conflict_handler= 参数:

注意: ArgumentParser 对象只能移除一个行为如果它所有的选项字符串都被重写。所以，在上面的例子中，旧的 -f/--foo 行为回合 -f 行为保持一样, 因为只有 --foo 选项字符串被重写。

add_help {#add-help}

默认情况下，ArgumentParser 对象添加一个简单的显示解析器帮助信息的选项。举个例子，考虑一个名为 myprogram.py 的文件包含如下代码:

如果 -h or --help 在命令行中被提供, 参数解析器帮助信息会打印:

有时候可能会需要关闭额外的帮助信息。这可以通过在 ArgumentParser 中设置 add_help= 参数为 False 来实现。

帮助选项一般为 -h/--help。如果 prefix_chars= 被指定并且没有包含 - 字符，在这种情况下， -h --help 不是有效的选项。此时， prefix_chars 的第一个字符将用作帮助选项的前缀。

exit_on_error {#exit-on-error}

正常情况下，当你向 ArgumentParser 的 parse_args() 方法传入一个无效的参数列表时，它将会退出并发出错误信息。

如果用户想要手动捕获错误，可通过将 exit_on_error 设为 False 来启用该特性:

3.9 新版功能.

添加参数 add_argument {#添加参数-add-argument}

给一个 ArgumentParser 添加程序参数信息是通过调用 add_argument() 方法完成的。通常，这些调用指定 ArgumentParser 如何获取命令行字符串并将其转换为对象。这些信息在 parse_args() 调用时被存储和使用。

例如：

然后，调用 parse_args() 将返回一个具有 integers 和 accumulate 两个属性的对象。integers 属性将是一个包含一个或多个整数的列表，而 accumulate 属性当命令行中指定了 --sum 参数时将是 sum() 函数，否则则是 max() 函数。

add_argument() 方法

定义单个的命令行参数应当如何解析：

| 参数名称 | 描述 | |---------------|--------------------------------------| | name or flags | 一个命名或者一个选项字符串的列表，例如 foo 或 -f, --foo。 | | action | 当参数在命令行中出现时使用的动作基本类型。 | | nargs | 命令行参数应当消耗的数目。 | | const | 被一些 action 和 nargs 选择所需求的常数。 | | default | 当参数未在命令行中出现并且也不存在于命名空间对象时所产生的值。 | | type | 命令行参数应当被转换成的类型。 | | choices | 由允许作为参数的值组成的序列。 | | required | 此命令行选项是否可省略（仅选项可用）。 | | help | 一个此选项作用的简单描述。 | | metavar | 在使用方法消息中使用的参数值示例。 | | dest | 被添加到 parse_args() 所返回对象上的属性名。 |

name or flags {#name-or-flags}

add_argument() 方法必须知道它是否是一个选项，例如 -f 或 --foo，或是一个位置参数，例如一组文件名。第一个传递给 add_argument() 的参数必须是一系列旗标或者是一个简单的参数名。例如，可选参数可以被这样创建:

而位置参数可以这么创建:

当 parse_args() 被调用，选项会以 - 前缀识别，剩下的参数则会被假定为位置参数:

action {#action}

ArgumentParser 对象将命令行参数与动作相关联。这些动作可以做与它们相关联的命令行参数的任何事，尽管大多数动作只是简单的向 parse_args() 返回的对象上添加属性。action 命名参数指定了这个命令行参数应当如何处理。供应的动作有：

store - 存储参数的值。这是默认的动作。例如:
store_const - 存储被 const 命名参数指定的值。 store_const 动作通常用在选项中来指定一些标志。例如:
store_true and store_false - 这些是 store_const 分别用作存储 True 和 False 值的特殊用例。另外，它们的默认值分别为 False 和 True。例如:
append - 存储一个列表，并且将每个参数值追加到列表中。在允许多次使用选项时很有用。例如:
append_const - 这存储一个列表，并将 const 命名参数指定的值追加到列表中。（注意 const 命名参数默认为 None。）append_const 动作一般在多个参数需要在同一列表中存储常数时会有用。例如:
count - 计算一个关键字参数出现的数目或次数。例如，对于一个增长的详情等级来说有用:

请注意，default 将为 None，除非显式地设为 0。
help - 打印所有当前解析器中的选项和参数的完整帮助信息，然后退出。默认情况下，一个 help 动作会被自动加入解析器。关于输出是如何创建的，参与 ArgumentParser。
version - 期望有一个 version= 命名参数在 add_argument() 调用中，并打印版本信息并在调用后退出:
extend - 这会存储一个列表，并将每个参数值加入到列表中。示例用法:

3.8 新版功能.

你还可以通过传递一个 Action 子类或实现相同接口的其他对象来指定任意操作。 BooleanOptionalAction 在 argparse 中可用并会添加对布尔型操作例如 --foo 和 --no-foo 的支持:

3.9 新版功能.

创建自定义动作的推荐方式是扩展 Action，重写 __call__ 方法以及可选的 __init__ 和 format_usage 方法。

一个自定义动作的例子:

更多描述，见 Action。

nargs {#nargs}

ArgumentParser 对象通常关联一个单独的命令行参数到一个单独的被执行的动作。 nargs 命名参数关联不同数目的命令行参数到单一动作。支持的值有：

N （一个整数）。命令行中的 N 个参数会被聚集到一个列表中。例如:

>>>

注意 nargs=1 会产生一个单元素列表。这和默认的元素本身是不同的。
'?'。如果可能的话，会从命令行中消耗一个参数，并产生一个单独项。如果当前没有命令行参数，将会产生 default 值。注意对于可选参数来说，还有一个额外情况 ------ 出现了选项字符串但没有跟随命令行参数，在此情况下将会产生 const 值。一些说明这种情况的例子如下:

nargs='?' 的一个更普遍用法是允许可选的输入或输出文件:
'*'。所有当前命令行参数被聚集到一个列表中。注意通过 nargs='*' 来实现多个位置参数通常没有意义，但是多个选项是可能的。例如:
'+'。和 '*' 类似，所有当前命令行参数被聚集到一个列表中。另外，当前没有至少一个命令行参数时会产生一个错误信息。例如:

如果不提供 nargs 命名参数，则消耗参数的数目将被 action 决定。通常这意味着单一项目（非列表）消耗单一命令行参数。

const {#const}

add_argument() 的 const 参数用于保存不从命令行中读取但被各种 ArgumentParser 动作需求的常数值。最常用的两例为：

当 add_argument() 通过 action='store_const' 或 action='append_const 调用时。这些动作将 const 值添加到 parse_args() 返回的对象的属性中。在 action 的描述中查看案例。
当 add_argument() 通过选项（例如 -f 或 --foo）调用并且 nargs='?' 时。这会创建一个可以跟随零个或一个命令行参数的选项。当解析命令行时，如果选项后没有参数，则将用 const 代替。在 nargs 描述中查看案例。

对 'store_const' 和 'append_const' 动作， const 命名参数必须给出。对其他动作，默认为 None。

默认值 {#默认值}

所有选项和一些位置参数可能在命令行中被忽略。add_argument() 的命名参数 default，默认值为 None，指定了在命令行参数未出现时应当使用的值。对于选项， default 值在选项未在命令行中出现时使用:

如果目标命名空间已经有一个属性集，则 default 动作不会覆盖它:

如果 default 值是一个字符串，解析器解析此值就像一个命令行参数。特别是，在将属性设置在 Namespace 的返回值之前，解析器应用任何提供的 type 转换参数。否则解析器使用原值:

对于 nargs 等于 ? 或 * 的位置参数， default 值在没有命令行参数出现时使用。

提供 default=argparse.SUPPRESS 导致命令行参数未出现时没有属性被添加:

type {#type}

默认情况下，解析器会将命令行参数当作简单字符串读入。然而，命令行字符串经常应当被解读为其他类型，例如 float 或 int。 add_argument() 的 type 关键字允许执行任何必要的类型检查和类型转换。

如果 type 关键字使用了 default关键字，则类型转换器仅会在默认值为字符串时被应用。

传给 type 的参数可以是任何接受单个字符串的可调用对象。如果函数引发了 ArgumentTypeError, TypeError 或 ValueError，异常会被捕获并显示经过良好格式化的错误消息。其他异常类型则不会被处理。

普通内置类型和函数可被用作类型转换器:

用户自定义的函数也可以被使用:

不建议将 bool()函数用作类型转换器。它所做的只是将空字符串转为 False 而将非空字符串转为 True。这通常不是用户所想要的。

通常，type 关键字是仅应被用于只会引发上述三种被支持的异常的简单转换的便捷选项。任何具有更复杂错误处理或资源管理的转换都应当在参数被解析后由下游代码来完成。

例如，JSON 或 YAML 转换具有复杂的错误情况，要求给出比 type 关键字所能给出的更好的报告。 JSONDecodeError 将不会被良好地格式化而 FileNotFound 异常则完全不会被处理。

即使 FileType 在用于 type 关键字时也存在限制。如果一个参数使用了 FileType 并且有一个后续参数出错，则将报告一个错误但文件并不会被自动关闭。在此情况下，更好的做法是等待直到解析器运行完毕再使用 with 语句来管理文件。

对于简单地检查一组固定值的类型检查器，请考虑改用 choices 关键字。

choices {#choices}

某些命令行参数应当从一组受限的值中选择。这可以通过将一个序列对象作为 choices 关键字参数传给 add_argument() 来处理。当执行命令行解析时，参数值将被检查，如果参数不是可接受的值之一就将显示错误消息:

请注意 choices 序列包含的内容会在执行任意 type 转换之后被检查，因此 choices 序列中对象的类型应当与指定的 type 相匹配:

任何序列都可作为 choices 值传入，因此 list 对象、tuple 对象以及自定义序列都是受支持的。

不建议使用 enum.Enum，因为要控制其在用法、帮助和错误消息中的外观是很困难的。

已格式化的选项会覆盖默认的 metavar ，该值一般是派生自 dest 。这通常就是你所需要的，因为用户永远不会看到 dest 形参。如果不想要这样的显示（或许因为有很多选择），只需指定一个显式的 metavar。

required {#required}

通常，argparse 模块会认为 -f 和 --bar 等旗标是指明 可选的 参数，它们总是可以在命令行中被忽略。要让一个选项成为 必需的 ，则可以将 True 作为 required= 关键字参数传给 add_argument():

如这个例子所示，如果一个选项被标记为 required，则当该选项未在命令行中出现时，parse_args() 将会报告一个错误。

注解: 必需的选项通常被认为是不适宜的，因为用户会预期 options 都是 可选的，因此在可能的情况下应当避免使用它们。

help {#help}

help 值是一个包含参数简短描述的字符串。当用户请求帮助时（一般是通过在命令行中使用 -h 或 --help 的方式），这些 help 描述将随每个参数一同显示:

help 字符串可包括各种格式描述符以避免重复使用程序名称或参数 default 等文本。有效的描述符包括程序名称 %(prog)s 和传给 add_argument() 的大部分关键字参数，例如 %(default)s, %(type)s 等等:

由于帮助字符串支持 %-formatting，如果你希望在帮助字符串中显示 % 字面值，你必须将其转义为 %%。

argparse 支持静默特定选项的帮助，具体做法是将 help 的值设为 argparse.SUPPRESS:

metavar {#metavar}

当 ArgumentParser 生成帮助消息时，它需要用某种方式来引用每个预期的参数。默认情况下，ArgumentParser 对象使用 dest 值作为每个对象的 "name"。默认情况下，对于位置参数动作，dest 值将被直接使用，而对于可选参数动作，dest 值将被转为大写形式。因此，一个位置参数 dest='bar' 的引用形式将为 bar。一个带有单独命令行参数的可选参数 --foo 的引用形式将为 FOO。示例如下:

可以使用 metavar 来指定一个替代名称:

请注意 metavar 仅改变 显示的 名称 - parse_args()对象的属性名称仍然会由 dest 值确定。

不同的 nargs 值可能导致 metavar 被多次使用。提供一个元组给 metavar 即为每个参数指定不同的显示信息:

dest {#dest}

大多数 ArgumentParser 动作会添加一些值作为 parse_args() 所返回对象的一个属性。该属性的名称由 add_argument() 的 dest 关键字参数确定。对于位置参数动作，dest 通常会作为 add_argument() 的第一个参数提供:

对于可选参数动作，dest 的值通常取自选项字符串。 ArgumentParser 会通过接受第一个长选项字符串并去掉开头的 -- 字符串来生成 dest 的值。如果没有提供长选项字符串，则 dest 将通过接受第一个短选项字符串并去掉开头的 - 字符来获得。任何内部的 - 字符都将被转换为 _ 字符以确保字符串是有效的属性名称。下面的例子显示了这种行为:

dest 允许提供自定义属性名称:

Action 类 {#Action-类}

Action 类实现了 Action API，它是一个返回可调用对象的可调用对象，返回的可调用对象可处理来自命令行的参数。任何遵循此 API 的对象均可作为 action 形参传给 add_argument()。

class argparse.``Action(option_strings , dest , nargs=None , const=None , default=None , type=None , choices=None , required=False , help=None , metavar=None)

Action 对象会被 ArgumentParser 用来表示解析从命令行中的一个或多个字符串中解析出单个参数所必须的信息。 Action 类必须接受两个位置参数以及传给 ArgumentParser.add_argument() 的任何关键字参数，除了 action 本身。

Action 的实例（或作为or return value of any callable to the action 形参的任何可调用对象的返回值）应当定义 "dest", "option_strings", "default", "type", "required", "help" 等属性。确保这些属性被定义的最容易方式是调用 Action.__init__。

Action 的实例应当为可调用对象，因此所有子类都必须重写 __call__ 方法，该方法应当接受四个形参:

parser - 包含此动作的 ArgumentParser 对象。
namespace - 将由 parse_args() 返回的 Namespace 对象。大多数动作会使用 setattr() 为此对象添加属性。
values - 已关联的命令行参数，并提供相应的类型转换。类型转换由 add_argument() 的 type 关键字参数来指定。
option_string - 被用来发起调用此动作的选项字符串。 option_string 参数是可选的，且此参数在动作关联到位置参数时将被略去。

__call__ 方法可以执行任意动作，但通常将基于 dest 和 values 来设置 namespace 的属性。

动作子类可定义 format_usage 方法，该方法不带参数，所返回的字符串将被用于打印程序的用法说明。如果未提供此方法，则将使用适当的默认值。

解析参数 parse_args() {#解析参数-parse-args}

ArgumentParser 通过 parse_args() 方法解析参数。它将检查命令行，把每个参数转换为适当的类型然后调用相应的操作。在大多数情况下，这意味着一个简单的 Namespace 对象将从命令行解析出的属性构建：

在脚本中，通常 parse_args() 会被不带参数调用，而 ArgumentParser 将自动从 sys.argv 中确定命令行参数。

parse_args() {#parse-args}

ArgumentParser.parse_args(args=None , namespace=None)

将参数字符串转换为对象并将其设为命名空间的属性。返回带有成员的命名空间。

之前对 add_argument() 的调用决定了哪些对象被创建以及它们如何被赋值。请参阅 add_argument() 的文档了解详情。
- args - 要解析的字符串列表。默认值是从 sys.argv 获取。
- namespace - 用于获取属性的对象。默认值是一个新的空 Namespace 对象。

选项值语法 {#选项值语法}

parse_args() 方法支持多种指定选项值的方式（如果它接受选项的话）。在最简单的情况下，选项和它的值是作为两个单独参数传入的:

对于长选项（名称长度超过一个字符的选项），选项和值也可以作为单个命令行参数传入，使用 = 分隔它们即可:

对于短选项（长度只有一个字符的选项），选项和它的值可以拼接在一起:

有些短选项可以使用单个 - 前缀来进行合并，如果仅有最后一个选项（或没有任何选项）需要值的话:

无效的参数 {#无效的参数}

在解析命令行时，parse_args() 会检测多种错误，包括有歧义的选项、无效的类型、无效的选项、错误的位置参数个数等等。当遇到这种错误时，它将退出并打印出错误文本同时附带用法消息:

包含 `-` 的参数 {#包含-的参数}

parse_args() 方法会在用户明显出错时尝试给出错误信息，但某些情况本身就存在歧义。例如，命令行参数 -1 可能是尝试指定一个选项也可能是尝试提供一个位置参数。 parse_args() 方法在此会谨慎行事：位置参数只有在它们看起来像负数并且解析器中没有任何选项看起来像负数时才能以 - 打头。:

如果你有必须以 - 打头的位置参数并且看起来不像负数，你可以插入伪参数 '--' 以告诉 parse_args() 在那之后的内容是一个位置参数: