standalone-python-scripts

独立 Python 脚本

编写单文件 Python 脚本的指南：使用 PEP 723 内联元数据和 uv 管理依赖项。

适用场景

• 创建独立的 Python 脚本（单文件，无 pyproject.toml）
• 编写 CLI 工具或实用脚本
• 构建包含外部依赖项的快速自动化脚本或一次性脚本

**不适用于：**包含多个模块、软件包或 pyproject.toml/setup.py 结构的较大型 Python 项目。

操作步骤

1. 检查 Python 版本支持情况 — 设置 requires-python 前，确认目标版本尚未结束生命周期（EOL），且距离 EOL 至少还有一年。查看 https://devguide.python.org/versions/ 了解当前状态。只有用户明确要求时，才选择更旧的版本。

2. 尽量减少依赖项 — 仅在外部软件包能明显节省时间或提供必要功能时才添加。条件允许时，优先使用标准库。

3. 添加 PEP 723 内联元数据 — 使用 # /// script 块格式在脚本顶部声明依赖项：

   # /// script
   # requires-python = ">=3.12"
   # dependencies = [
   #     "click>=8.1",
   #     "arrow>=1.3",
   # ]
   # ///
   

4. 使用 uv shebang — 脚本依赖非标准库时，使用：

   #!/usr/bin/env -S uv run --script
   

   这样即可直接执行：./script.py

5. 优先使用 Click 解析参数 — 脚本需要 CLI 参数时，优先使用 Click，而不是 argparse 或其他库。

6. 优先使用 Arrow 处理日期和时间 — 脚本需要处理日期或时间时，优先使用 Arrow，而不是 datetime 或其他库。

7. 设置可执行权限 — 创建脚本后，运行 chmod +x script.py，使其可直接执行。

示例

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "click>=8.1",
#     "arrow>=1.3",
# ]
# ///

import click
import arrow

@click.command()
@click.option("--name", default="World", help="Name to greet")
@click.option("--date", is_flag=True, help="Show today's date")
def main(name, date):
    """Greet someone and optionally show the date."""
    click.echo(f"Hello, {name}!")
    if date:
        click.echo(f"Today is {arrow.now().format('YYYY-MM-DD')}")

if __name__ == "__main__":
    main()

常见问题

• **过度设计：**不要为简单任务添加依赖项。如果 datetime 已够用，就不要添加 Arrow。如果 argparse 已够用，就不要添加 Click。
• **缺少 shebang：**没有 #!/usr/bin/env -S uv run --script，就无法通过 ./script.py 直接运行脚本。
• 元数据块无效：# /// script 块必须位于顶部，并严格遵循 PEP 723 格式。
• **忘记设置 chmod：**脚本需要执行权限（chmod +x）才能直接运行。
• **版本漂移：**在依赖项中指定最低版本，避免 uv 解析软件包时出现意外。

验证

创建脚本后：

1. 检查元数据块是否有效：uv run --script script.py --help
2. 直接运行脚本：./script.py
3. 确认依赖项已安装，且脚本按预期工作

快速检查清单：

Is the Python version still supported (not EOL, >1 year to EOL)?
Does the script have a shebang line?
Is the PEP 723 metadata block present and valid?
Are dependencies minimal and justified?
Is the script executable (chmod +x)?