Poetry类Python CLI工具全局命令实现原理及自制可分发包方法

在Windows上用pip安装Poetry时，pip会自动生成可执行脚本并放到Python安装目录下的Scripts文件夹里。多数时候你安装Python时，这个Scripts目录已经被默认添加到系统PATH中了——你没看到Poetry相关的PATH条目，是因为PATH里的是Python的Scripts路径，而非Poetry自身的目录，系统会从这个目录里找到poetry.exe（或poetry.cmd）来执行命令。

举个例子，假设你的Python安装在C:\Python311，那Scripts目录就是C:\Python311\Scripts，poetry.exe就存放在这里。只要这个目录在PATH里，不管你在哪个终端目录，输入poetry都会触发这个可执行文件。

要做一个能全局调用的Python包，核心是在包配置里声明控制台脚本入口，pip会自动帮你生成系统可识别的执行文件。具体步骤如下：

1. 搭建基础包结构 #

先整理好包的基本目录结构：

mycli/
├── mycli/
│   ├── __init__.py
│   └── main.py
└── pyproject.toml

2. 编写核心命令逻辑 #

在mycli/main.py里实现你的命令功能，比如：

def main():
    print("这是我的全局命令工具！")

if __name__ == "__main__":
    main()

3. 配置pyproject.toml #

在pyproject.toml里添加console_scripts配置，关联命令名称和入口函数：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mycli"
version = "0.1.0"
authors = [{"name" = "你的名字", "email" = "你的邮箱"}]
description = "测试用全局命令工具"
readme = "README.md"
requires-python = ">=3.8"

[project.scripts]
mycli = "mycli.main:main"

这里的mycli = "mycli.main:main"表示：生成名为mycli的全局命令，入口是mycli包下main模块里的main函数。

4. 打包并上传到PyPI #

• 安装打包与上传工具：pip install build twine
• 生成包文件：python -m build
• 上传到PyPI：twine upload dist/*

其他用户安装你的包时，pip会自动在他们的PythonScripts目录（Windows）或bin目录（Linux/macOS）生成对应的可执行文件，只要该目录在PATH里，就能直接输入mycli调用你的工具。

补充说明 #

• 如果用户的PythonScripts目录不在PATH里，他们可以手动添加，或者用python -m mycli来调用，但多数Python安装都会默认把这个目录加入PATH。
• 若要做复杂命令行工具，可以用click或argparse库处理参数，提升工具实用性。

内容的提问来源于stack exchange，提问作者bitclip