Python Fire 命令行工具使用完全指南

Python Fire 命令行工具使用完全指南

python-fire Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object. 项目地址: https://gitcode.com/gh_mirrors/py/python-fire

什么是 Python Fire

Python Fire 是一个可以将任何 Python 对象自动转换为命令行接口(CLI)的库。它通过简单的 API 调用，让开发者能够快速为 Python 代码创建命令行工具，而无需编写繁琐的参数解析代码。

基础使用方式

基本命令结构

每个 Fire 命令都对应一个 Python 组件。最简单的 Fire 命令是直接运行程序而不带任何额外参数，这对应于调用 Fire() 函数的 Python 组件。

获取帮助信息

在任何 Fire 命令后添加 --help 或 -h 可以查看该命令对应的 Python 组件信息以及扩展命令的各种方式。

参数分隔符

Fire 的标志参数需要使用独立的分隔符 -- 与 Fire 命令分开。例如，要进入交互模式，可以在任何命令后添加 -- -i 或 -- --interactive。

对象成员访问

访问对象成员

如果命令对应一个对象，可以通过添加成员名称作为新参数来扩展命令。例如，对象有一个名为 whack 的方法，添加 whack 参数后，新命令就对应这个方法。

访问字典成员

对于字典对象，可以通过添加键名作为参数来访问对应的值。例如：widget function-that-returns-dict key 将访问字典中 key 对应的值。

访问列表/元组成员

对于列表或元组，可以通过添加索引作为参数来访问元素。例如：widget function-that-returns-list 2 访问列表的第三个元素。

函数调用与类实例化

调用函数

如果命令对应一个函数，可以通过添加函数参数来扩展命令。参数可以按位置或名称指定。例如：

def double(value=0):
    return 2 * value

可以这样调用：

• 命名参数：command --value 5
• 位置参数：command 5

强制函数求值

对于接受可变数量参数的函数，可以添加分隔符(默认为连字符"-")来强制函数求值，防止右侧参数被函数调用消耗。

类实例化

如果命令对应一个类，可以通过添加 __init__ 函数的参数来实例化类。参数必须使用标志语法按名称指定。

标志参数使用

标志参数语法

要在 Fire CLI 中设置标志，需要在最后的独立 -- 参数后添加标志。例如：widget bang --noise=boom -- --alsologtostderr 中，--noise 被 Fire 消耗，而 --alsologtostderr 被视为普通标志。

Python Fire 的核心标志

交互模式 (--interactive/-i)

使用 widget -- --interactive 进入交互模式，这将启动 IPython REPL，并预定义 widget 变量。

注意：需要安装 ipython 包才能使用 IPython REPL。

自动补全脚本 (--completion)

使用 widget -- --completion 生成 Bash 补全脚本，或 widget -- --completion fish 生成 Fish shell 补全脚本。

帮助信息 (--help/-h)

在任何 Fire 命令后添加 -- --help 获取使用信息。当发生错误时也会自动显示帮助。

执行跟踪 (--trace)

使用 widget whack 5 -- --trace 获取执行跟踪信息，了解 Fire 命令的执行步骤。

分隔符设置 (--separator)

默认分隔符是 -。可以通过 --separator 标志更改分隔符。例如：

display hello - upper       # 使用默认分隔符
display - SEP upper -- --separator SEP  # 更改分隔符为"SEP"

详细模式 (--verbose/-v)

添加 -v 或 --verbose 标志启用详细模式，显示更多调试信息，包括私有成员。

实际应用示例

示例1：简单函数调用

# greet.py
import fire

def greet(name="World"):
    return f"Hello, {name}!"

if __name__ == "__main__":
    fire.Fire(greet)

使用方法：

python greet.py            # Hello, World!
python greet.py --name Alice  # Hello, Alice!
python greet.py Alice      # Hello, Alice!

示例2：类实例化

# calculator.py
import fire

class Calculator:
    def __init__(self, initial_value=0):
        self.value = initial_value
    
    def add(self, x):
        self.value += x
        return self.value
    
    def multiply(self, x):
        self.value *= x
        return self.value

if __name__ == "__main__":
    fire.Fire(Calculator)

使用方法：

python calculator.py --initial-value 10 add 5      # 15
python calculator.py --initial-value 10 multiply 3 # 30

最佳实践

1. 命名规范：使用小写字母和连字符命名命令行参数，对应 Python 中的下划线命名
2. 帮助文档：为函数和类添加文档字符串，这些将显示在帮助信息中
3. 参数验证：在函数内部进行参数验证，而不是依赖 Fire 的基本类型转换
4. 错误处理：考虑添加自定义错误处理逻辑，提供更友好的错误信息

总结

Python Fire 提供了一种极其简单的方式将 Python 代码转换为命令行工具。通过本文介绍的各种功能和技巧，开发者可以快速构建功能丰富、用户友好的命令行界面，而无需花费大量时间在参数解析上。无论是简单的脚本还是复杂的应用程序，Python Fire 都能显著提高开发效率。

python-fire Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object. 项目地址: https://gitcode.com/gh_mirrors/py/python-fire