parser

命令行解析框架被分成几个子模块：

  • parser.argument

  • parser.context （不要与高层混淆 context ！）

  • parser.parser

所有API文档如下。

class invoke.parser.parser.ParseResult(*args: Any, **kwargs: Any)

具有一些额外的解析相关属性的类似列表的对象。

具体地说，一个 .remainder 属性，该属性是在 -- 在任何已分析的argv列表中；以及 .unparsed 属性，即无法分析的令牌的列表。

在 1.0 版本加入.

__init__(*args: Any, **kwargs: Any) → None
__weakref__

对象的弱引用列表

class invoke.parser.parser.Parser(contexts: Iterable[ParserContext] = (), initial: ParserContext | None = None, ignore_unknown: bool = False)

创建有意识的解析器 contexts 和可选 initial 背景。

contexts 应该是一个可迭代的 Context 在分析过程中遇到新的上下文名称时将搜索的实例。这些上下文确定它们后面可以跟随什么标志，以及给定的标志是否取值。

initial 是可选的，将用于在分析运行开始时确定“core”选项/标志的有效性(如果遇到任何)。

ignore_unknown 确定在找到未映射到的任何成员的上下文时应执行的操作 contexts 。默认情况下为 False 这意味着任何未知的上下文都会导致解析错误异常。如果 True ，遇到未知上下文会暂停解析并填充返回值的 .unparsed 属性和剩余的分析令牌。

在 1.0 版本加入.

__init__(contexts: Iterable[ParserContext] = (), initial: ParserContext | None = None, ignore_unknown: bool = False) → None
parse_argv(argv: List[str]) → ParseResult

解析argv样式的令牌列表 argv 。

返回一个列表(实际上是子类， ParseResult )的 ParserContext 对象中找到它们的顺序相匹配的 argv 并包含 Argument 具有基于任何给定标志的更新值的对象。

假定任何程序名称都已被删除。好：：

Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])

错误：：

Parser(...).parse_argv(['invoke', '--core-opt', ...])
参数:

argv -- 参数字符串标记的列表。

返回:

A ParseResult (A) list 子类包含一些数量 ParserContext 对象)。

在 1.0 版本加入.

__weakref__

对象的弱引用列表

class invoke.parser.context.ParserContext(name: str | None = None, aliases: Iterable[str] = (), args: Iterable[Argument] = ())

使用标志及其格式的知识分析上下文。

通常与核心计划或任务相关联。

当通过解析器运行时，还将保存解析器填充的运行时值。

在 1.0 版本加入.

__init__(name: str | None = None, aliases: Iterable[str] = (), args: Iterable[Argument] = ()) → None

创建新的 ParserContext 名为 name 同 aliases 。

name 是可选的，如果给定，则应为字符串。它用于区分ParserContext对象，并在确定哪些输入块可能属于给定的ParserContext时在解析器中使用。

aliases 也是可选的，应该是包含字符串的可迭代。当试图在其输入中“找到”给定的上下文时，解析将接受任何别名。

可能会给一个或多个 args ，这是呼叫的快速替代方案 for arg in args: self.add_arg(arg) 在初始化之后。

__repr__() → str

返回epr(Self)。

__weakref__

对象的弱引用列表

add_arg(*args: Any, **kwargs: Any) → None

添加给定的 Argument (或构造函数参数)添加到此上下文中。

有问题的参数将添加到以下dict属性中：

  • args ：“正常”访问，即给定的名称直接公开为键。

  • flags ：“旗帜式”访问，即给定的名称被转换为CLI标志，例如 "foo" 可通过以下方式访问 flags['--foo'] 。

  • inverse_flags ：类似于 flags 但仅包含缺省为True的布尔标志的“逆”版本。这允许解析器跟踪例如 --no-myflag 并将其转换为 myflag 论点。

在 1.0 版本加入.

property as_kwargs: Dict[str, Any]

此上下文的参数值由其 .name 属性。

生成适合在Python上下文中使用的字典，其中名为 foo-bar 变得可访问，因为 foo_bar 。

在 1.0 版本加入.

flag_names() → Tuple[str, ...]

类似于 help_tuples 但只返回标志名称，而不返回帮助。

具体地说，所有旗帜名称都被粗略地压平了。

在 1.0 版本加入.

help_for(flag: str) → Tuple[str, str]

返回2元组 (flag-spec, help-string) 对于给定的 flag 。

在 1.0 版本加入.

help_tuples() → List[Tuple[str, str | None]]

为所有成员参数返回帮助元组的排序可迭代。

大概是这样的：

  • 常规排序按字母数字排序

  • 短旗压倒长旗

  • 与 only 长旗和 no 短旗将首先出现。

  • 当参数有多个长或短标志时，它将使用最有利(按字母顺序最低)的候选进行排序。

这将产生如下帮助列表：：

--alpha, --zeta # 'alpha' wins
--beta
-a, --query # short flag wins
-b, --argh
-c

在 1.0 版本加入.

invoke.parser.context.flag_key(arg: Argument) → List[str | int]

获取用于对CLI标志进行排序的有用的INT键列表。

在 1.0 版本加入.

class invoke.parser.argument.Argument(name: str | None = None, names: ~typing.Iterable[str] = (), kind: ~typing.Any = <class 'str'>, default: ~typing.Any | None = None, help: str | None = None, positional: bool = False, optional: bool = False, incrementable: bool = False, attr_name: str | None = None)

A命令行参数/标志。

参数:

  • name -- 语法糖For names=[<name>] 。两者兼得 name 和 names 是无效的。

  • names -- 此参数的有效标识符列表。例如，可以使用名称列表定义“Help”参数 ['-h', '--help'] 。

  • kind -- 输入工厂和解析器提示。例如。 int 会将解析的默认文本值转换为一个Python整数；以及 bool 将告诉解析器不要期望实际值，而是将参数视为切换/标志。

  • default -- 如果命令行上没有给定值，则解析器可以使用默认值。

  • help -- 帮助文本，旨在与一起使用 --help 。

  • positional -- 此参数的值是否可以按位置给出。什么时候 False (默认)参数必须显式命名。

  • optional -- 此(非``bool``)参数是否需要值。

  • incrementable -- 不管这是不是 (int )参数将被递增，而不是被覆盖/赋值。

  • attr_name -- 一个Python标识符/属性友好名称，通常在以下情况下使用下划线版本填充 name/names 包含破折号。

在 1.0 版本加入.

__init__(name: str | None = None, names: ~typing.Iterable[str] = (), kind: ~typing.Any = <class 'str'>, default: ~typing.Any | None = None, help: str | None = None, positional: bool = False, optional: bool = False, incrementable: bool = False, attr_name: str | None = None) → None
__repr__() → str

返回epr(Self)。

__weakref__

对象的弱引用列表

property got_value: bool

返回该参数是否曾被赋予(非默认)值。

对于大多数参数类型，这只是检查内部存储的值是否是非``None``；对于其他类型，如 list 种类，可以使用不同的支票。

在 1.3 版本加入.

property name: str | None

此参数的规范属性友好名称。

会是 attr_name (如果指定给构造函数)或 names 否则的话。

在 1.0 版本加入.

set_value(value: Any, cast: bool = True) → None

实际显式设置值的API调用。

集 self.raw_value 至 value 直接去吧。

集 self.value 至 self.kind(value) ，除非：

  • cast=False ，在这种情况下，也使用原始值。

  • self.kind==list ，在这种情况下，该值被追加到 self.value 而不是强制转换和覆盖。

  • self.incrementable==True 在这种情况下，该值被忽略，而当前值(假定为int)只是递增。

在 1.0 版本加入.