在現(xiàn)代 Python 開發(fā)生態(tài)中，命令行工具（CLI）是自動(dòng)化、腳本化和工具鏈集成的核心。借助 uv（超快的 Python 包管理器）和 PyPI，我們可以快速開發(fā)、打包、發(fā)布一個(gè) CLI 工具，并讓用戶無需安裝 Python 環(huán)境就能通過 uvx 直接運(yùn)行！

本文將帶你完成整個(gè)流程：

• 開發(fā)一個(gè)最簡(jiǎn) CLI 工具
• 使用標(biāo)準(zhǔn) src/ 項(xiàng)目結(jié)構(gòu)
• 打包并發(fā)布到 PyPI
• 用戶通過 uvx xccli 一鍵使用

為什么選擇 uv + pyproject.toml

• uv 是由 Astral 開發(fā)的超快 Python 包安裝器（比 pip 快 10–100 倍）
• uvx 可以直接運(yùn)行 PyPI 上的 CLI 工具，無需 pip install
• pyproject.toml 是現(xiàn)代 Python 項(xiàng)目的標(biāo)準(zhǔn)配置文件（取代 setup.py）
• src/ 布局 避免開發(fā)時(shí)意外導(dǎo)入本地模塊，更安全

開發(fā)一個(gè)簡(jiǎn)單的命令行工具：mycli

我們要?jiǎng)?chuàng)建的工具叫 mycli，運(yùn)行后輸出一句問候。

1. 創(chuàng)建項(xiàng)目結(jié)構(gòu)

mkdir my-uv-demo
cd my-uv-demo

目錄結(jié)構(gòu)如下：

my-uv-demo/
├── pyproject.toml
└── src/
    └── my_uv_demo/
        ├── __init__.py
        └── mycli.py

2. 編寫核心邏輯：src/my_uv_demo/mycli.py

def main():
    print("Hello from mycli! ?")

if __name__ == "__main__":
    main()

3. 配置 pyproject.toml

[project]
name = "my-uv-demo"               # PyPI 上的包名（需唯一）
version = "0.1.0"
description = "A simple CLI tool built with uv"
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.12"
license = {text = "MIT"}
readme = "README.md"

# 定義命令行入口：mycli -> 調(diào)用 my_uv_demo.xccli:main
[project.scripts]
xccli = "my_uv_demo.mycli:main"

# 指定源碼在 src/ 下
[tool.hatch.build.targets.wheel]
packages = ["src/my_uv_demo"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

4. 本地測(cè)試（使用 uvx）

在項(xiàng)目根目錄運(yùn)行：

uvx --from . mycli

輸出：

Hello from mycli! ?

這說明你的 CLI 工具已能正常工作！

用戶如何使用你的工具

一旦發(fā)布成功，任何安裝了 uv 的用戶都可以直接運(yùn)行：

uvx xccli

無需：

• 安裝 Python（如果系統(tǒng)已有）
• 創(chuàng)建虛擬環(huán)境
• 手動(dòng) pip install

uvx 會(huì)自動(dòng)：

• 從 PyPI 下載你的包
• 解析依賴（本例無依賴）
• 在隔離環(huán)境中運(yùn)行 xccli 命令

輸出依然是：

Hello from mycli! ?

這就是現(xiàn)代 Python 工具分發(fā)的極致體驗(yàn)！

詳解原理

一旦發(fā)布成功，為什么uvx xccli 直接執(zhí)行就可以運(yùn)行？它是怎么找到這個(gè)xccli工具的？

一句話回答：uvx xccli 能直接運(yùn)行，是因?yàn)?uvx 會(huì)自動(dòng)在 PyPI 上查找哪個(gè)已發(fā)布的 Python 包提供了名為 xccli 的可執(zhí)行腳本（entry point），然后下載、安裝并運(yùn)行它。

這依賴于兩個(gè)核心機(jī)制：

• PyPI 包的元數(shù)據(jù)中聲明了 console_scripts（即 [project.scripts]）
• uvx 能解析這些元數(shù)據(jù)，并按需構(gòu)建臨時(shí)環(huán)境來執(zhí)行命令

詳細(xì)原理分解

第一步：你的包在 PyPI 上“注冊(cè)”了 mycli 命令

當(dāng)你在 pyproject.toml 中寫：

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

打包工具（如 hatchling）會(huì)在生成的 wheel（.whl 文件）中，將這條信息寫入 entry_points.txt 元數(shù)據(jù)文件，內(nèi)容類似：

[console_scripts]
mycli = my_uv_demo.mycli:main

當(dāng)你發(fā)布到 PyPI 后，這個(gè)元數(shù)據(jù)就公開可查。

這個(gè)機(jī)制最早來自 setuptools 的 console_scripts，現(xiàn)在是標(biāo)準(zhǔn)（PEP 621）。

第二步：用戶運(yùn)行 uvx xccli

當(dāng)用戶輸入：

uvx mycli

uvx 會(huì)執(zhí)行以下步驟：

1.查詢 PyPI：哪個(gè)包提供了 xccli？

uvx 會(huì)向 PyPI 的 API 發(fā)起請(qǐng)求（或使用本地緩存），查找所有已發(fā)布包中，console_scripts 包含 xccli 的包。

例如，它發(fā)現(xiàn)：

• 包 my-uv-demo（你發(fā)布的）聲明了 xccli = …
• 沒有其他包沖突（如果有多個(gè)，會(huì)報(bào)錯(cuò)或讓用戶指定）

注意：uvx 不是靠包名找命令，而是靠 命令名 → 反查提供者。

2.下載并安裝該包到隔離環(huán)境

uvx 會(huì)：

• 創(chuàng)建一個(gè)臨時(shí)虛擬環(huán)境（或復(fù)用緩存）
• 用 uv pip install my-uv-demo 安裝你的包（及其依賴）
• 安裝過程中，pip/uv 會(huì)根據(jù) console_scripts 自動(dòng)生成一個(gè)可執(zhí)行文件（如 xccli 或 xccli.exe）并放入環(huán)境的 bin/ 目錄

3.直接執(zhí)行該命令

最后，uvx 直接調(diào)用這個(gè) xccli 可執(zhí)行文件，等價(jià)于：

/path/to/temp-env/bin/mycli

但對(duì)用戶完全透明！

驗(yàn)證：手動(dòng)查看 PyPI 包的 entry points

你可以用 pip show 查看任意已安裝包的腳本：

pip install my-uv-demo  # 假設(shè)你已發(fā)布
pip show -f my-uv-demo | grep mycli

或者用 uv：

uv pip show -f my-uv-demo

你會(huì)看到類似：

console-scripts:
  xccli = my_uv_demo.xccli:main

常見問題 & 注意事項(xiàng)

Q1：如果兩個(gè)包都定義了 xccli 怎么辦？

A：uvx 會(huì)報(bào)錯(cuò)，提示沖突。因此命令名最好具有唯一性或品牌標(biāo)識(shí)（如 black、ruff、poetry）。

Q2：為什么不能直接用包名運(yùn)行？比如 uvx my-uv-demo？

A：因?yàn)榘?≠ 命令名。一個(gè)包可以提供多個(gè)命令（如 git 提供 git, git-receive-pack 等），所以必須通過命令名定位。

Q3：uvx 會(huì)不會(huì)每次都下載？

A：不會(huì)！uvx 會(huì)緩存已安裝的工具（默認(rèn)在 ～/.cache/uv/tools/），下次運(yùn)行極快。

總結(jié)

通過這套流程，你不僅開發(fā)了一個(gè) CLI 工具，還讓它像 npm 全局命令一樣簡(jiǎn)單易用，但速度更快、依賴更干凈。

到此這篇關(guān)于從零開始帶你使用Python開發(fā)一個(gè)命令行工具的文章就介紹到這了,更多相關(guān)Python命令行工具內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論