Poetry项目：创建可执行的命令行工具-Python教程-PHP中文网

Poetry项目：创建可执行的命令行工具

花韻仙語

发布： 2025-11-30 12:35:25

原创

313人浏览过

Poetry项目：创建可执行的命令行工具

本文介绍如何使用poetry将python项目配置为可直接从命令行运行的工具。通过在`pyproject.toml`文件中配置`[tool.poetry.scripts]`部分，开发者可以定义一个入口点，使项目模块在安装后能够像原生命令一样被调用，无需`python -m`。这种方法简化了命令行工具的部署和使用，提升了用户体验。

在Python项目开发中，尤其当项目旨在提供命令行实用工具时，我们通常希望用户能够像使用系统原生命令一样直接调用它，而不是每次都通过python -m your_module的方式。Poetry作为一款强大的Python依赖管理和打包工具，提供了简洁高效的方式来实现这一目标，即通过在pyproject.toml文件中定义可执行脚本。

配置可执行脚本

Poetry通过pyproject.toml文件中的[tool.poetry.scripts]部分来定义可执行的命令行工具。这个配置项允许你指定一个脚本名称（即用户在命令行中键入的命令）以及它对应的Python入口点。

基本语法：

[tool.poetry.scripts]
<command_name> = '<module_path>:<function_name>'

登录后复制

<command_name>：这是用户在终端中将要执行的命令名称。例如，如果你希望用户键入mycli来运行你的工具，那么这里就写mycli。
<module_path>：这是包含入口函数的Python模块的路径。例如，如果你的入口函数在my_package/console.py中，那么模块路径就是my_package.console。
<function_name>：这是在指定模块中被调用的函数名称。当用户执行<command_name>时，Poetry会确保调用这个函数。

示例：

假设你有一个名为my_package的Poetry项目，并且希望创建一个名为my_package_cli的命令行工具。这个工具的入口函数位于my_package/console.py文件中的run函数。

Yii 2.0.30

Yii 2.0.30，高性能的PHP5的web应用程序开发框架，通过一个简单的命令行工具yiic能快速创建一个web应用程序的代码框架，开发者可在生成的代码框架基

123

查看详情

创建或修改 pyproject.toml 文件： 在你的项目根目录下的pyproject.toml文件中，添加或修改[tool.poetry.scripts]部分，如下所示：

# pyproject.toml
[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "A sample Poetry project with a CLI"
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[tool.poetry.scripts]
my_package_cli = 'my_package.console:run' # 定义命令行工具

登录后复制

创建入口模块和函数： 在你的my_package目录（即与pyproject.toml中name字段对应的包名）下，创建console.py文件，并定义run函数：

# my_package/console.py

def run():
    """
    This function will be executed when 'my_package_cli' is called.
    """
    print("Hello from my_package_cli!")
    print("This is a command-line utility powered by Poetry.")

if __name__ == '__main__':
    run()

登录后复制

安装与使用

完成上述配置和代码编写后，你需要执行以下步骤来安装并使用你的命令行工具：

安装项目依赖： 在项目根目录下，运行Poetry的安装命令。这将安装项目的所有依赖，并根据[tool.poetry.scripts]配置创建可执行脚本。
```
poetry install
```
登录后复制
如果你的项目已经安装过，并且你只是添加了[tool.poetry.scripts]配置，你可能需要再次运行poetry install来更新环境。
执行命令行工具： 安装完成后，你就可以在Poetry项目的虚拟环境中直接调用你定义的命令了：
```
my_package_cli
```
登录后复制
你将看到my_package/console.py中run函数定义的输出：
```
Hello from my_package_cli!
This is a command-line utility powered by Poetry.
```
登录后复制

注意事项与总结

虚拟环境激活： poetry install会在当前Poetry项目对应的虚拟环境中创建可执行脚本。因此，你需要确保在执行my_package_cli命令时，该虚拟环境是激活的（例如，通过poetry shell进入）。
全局安装： 如果你将此Poetry项目打包并通过pip install安装到其他环境中（例如，作为PyPI包发布），那么这个命令行工具也会在目标环境中可用，无需手动激活Poetry虚拟环境。Poetry和pip都会负责将脚本添加到系统PATH中（或其等效位置）。
入口点清晰： 确保你的入口函数（如示例中的run）不接受任何参数，或者能够优雅地处理无参数调用，因为命令行工具通常会在不带参数的情况下被调用。如果需要处理命令行参数，你可以在run函数内部使用argparse等库来解析sys.argv。
错误处理： 在实际的命令行工具中，应包含适当的错误处理和用户友好的输出信息。

通过[tool.poetry.scripts]，Poetry极大地简化了Python项目向可执行命令行工具的转换过程，使其与传统的setup.py或手动脚本创建相比，更加现代化和便捷。这种方法不仅提升了开发效率，也为最终用户提供了更直观、更专业的工具使用体验。

以上就是Poetry项目：创建可执行的命令行工具的详细内容，更多请关注php中文网其它相关文章！