python-uv-scripts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Single-File Scripts with uv

使用uv开发Python单文件脚本

Expert guidance for creating production-ready, self-contained Python scripts using uv's inline dependency management (PEP 723).

本指南提供专业指导，教你如何使用uv的内联依赖管理（PEP 723）创建可用于生产环境的独立Python脚本。

Quick Start

快速开始

Create Your First uv Script

创建你的第一个uv脚本

python

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

python

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

/// script

requires-python = ">=3.11"

dependencies = [

"httpx>=0.27.0",

"rich>=13.0.0",

]

///

import httpx from rich import print

response = httpx.get("https://api.github.com") print(f"[green]Status: {response.status_code}[/green]")


Make it executable:

```bash
chmod +x script.py
./script.py  # uv automatically installs dependencies

import httpx from rich import print

response = httpx.get("https://api.github.com") print(f"[green]Status: {response.status_code}[/green]")


设置可执行权限：

```bash
chmod +x script.py
./script.py  # uv会自动安装依赖

Convert Existing Script

转换现有脚本

bash

undefined

bash

undefined

Add inline metadata to existing script

为现有脚本添加内联元数据

./tools/convert_to_uv.py existing_script.py

Validate PEP 723 metadata

验证PEP 723元数据

./tools/validate_script.py script.py

undefined

./tools/validate_script.py script.py

undefined

Core Concepts

核心概念

What is PEP 723?

什么是PEP 723？

PEP 723 defines inline script metadata for Python files:

python

undefined

PEP 723定义了Python文件的内联脚本元数据格式：

python

undefined

/// script

requires-python = ">=3.11"

dependencies = [

"package>=1.0.0",

]

///


**Benefits:**

- ✅ Dependencies live with the code
- ✅ No separate `requirements.txt`
- ✅ Reproducible execution
- ✅ Version constraints included
- ✅ Self-documenting


**优势：**

- ✅ 依赖与代码共存
- ✅ 无需单独的`requirements.txt`文件
- ✅ 可复现的执行环境
- ✅ 包含版本约束
- ✅ 自文档化

uv Script Execution Modes

uv脚本执行模式

Mode 1: Inline Dependencies (Recommended for utilities)

python

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

模式1：内联依赖（推荐用于工具类脚本）

python

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

/// script

dependencies = ["httpx"]

///


**Mode 2: Project Mode** (For larger scripts)

```bash
uv run script.py  # Uses pyproject.toml


**模式2：项目模式**（适用于较大的脚本）

```bash
uv run script.py  # 使用pyproject.toml中的配置

模式3：无依赖

python

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

Mode 3: No Dependencies

仅使用标准库

python

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

undefined

Standard library only

重要反模式：切勿这样做

—

❌ 切勿使用[tool.uv.metadata]

undefined

错误写法 - 会导致报错：

python

undefined

Critical Anti-Patterns: What NOT to Do

/// script

❌ NEVER Use [tool.uv.metadata]

requires-python = ">=3.11"

—

[tool.uv.metadata] # ❌ 此写法无效

—

purpose = "testing"

—

///

WRONG - This will cause errors:

python

undefined


**错误信息**：

```text
error: TOML parse error at line 3, column 7
unknown field `metadata`

原因：

[tool.uv.metadata]

不属于PEP 723规范，uv不支持该写法。

正确写法 - 使用Python文档字符串存储元数据：

python

undefined

/// script

requires-python = ">=3.11"

[tool.uv.metadata] # ❌ THIS DOES NOT WORK

dependencies = []

purpose = "testing"

///

—


**Error**:

```text
error: TOML parse error at line 3, column 7
unknown field `metadata`

Why:

[tool.uv.metadata]

is not part of PEP 723 and is not supported by uv.

CORRECT - Use Python docstrings for metadata:

python

undefined

""" 用途：测试自动化团队：DevOps 作者：team@example.com """


**支持的`tool.uv`字段**（如有需要）：

```python

/// script

requires-python = ">=3.11"

dependencies = []

///

[tool.uv]

—

exclude-newer = "2025-01-01T00:00:00Z" # 确保环境可复现

—

///

""" Purpose: Testing automation Team: DevOps Author: team@example.com """


**Valid `tool.uv` fields** (if needed):

```python

undefined

/// script

本仓库中的实际示例

requires-python = ">=3.11"

示例1：集群健康检查器

dependencies = []

—

[tool.uv]

—

exclude-newer = "2025-01-01T00:00:00Z" # For reproducibility

—

///

—

undefined

查看examples/03-production-ready/check_cluster_health_enhanced.py

当前基础版本：

python

#!/usr/bin/env python3
import subprocess

Real-World Examples from This Repository

需要手动安装依赖

Example 1: Cluster Health Checker

—

See examples/03-production-ready/check_cluster_health_enhanced.py

Current version (basic):

python

#!/usr/bin/env python3
import subprocess


**使用uv增强后的生产就绪版本**：

```python
#!/usr/bin/env -S uv run --script --quiet

Manual dependency installation required

/// script

—

requires-python = ">=3.11"

—

dependencies = [

—

"rich>=13.0.0",

—

"typer>=0.9.0",

—

]

—

///


**Enhanced with uv** (production-ready):

```python
#!/usr/bin/env -S uv run --script --quiet

""" 用途：集群健康监控团队：基础设施部 """

import typer from rich.console import Console from rich.table import Table

undefined

/// script

示例2：CEPH健康监控器

requires-python = ">=3.11"

—

dependencies = [

—

"rich>=13.0.0",

—

"typer>=0.9.0",

—

]

—

///

—

""" Purpose: Cluster health monitoring Team: Infrastructure """

import typer from rich.console import Console from rich.table import Table

undefined

查看examples/03-production-ready/ceph_health.py

模式：通过JSON API交互并生成结构化输出

Example 2: CEPH Health Monitor

本仓库中的最佳实践

—

1. 安全模式

See examples/03-production-ready/ceph_health.py

Pattern: JSON API interaction with structured output

查看reference/security-patterns.md获取完整安全指南，包括：

密钥管理（环境变量、密钥环、Infisical）
输入验证
依赖安全
文件操作安全
命令执行安全

Best Practices from This Repository

2. 版本固定策略

1. Security Patterns

—

See reference/security-patterns.md for complete security guide including:

Secrets management (environment variables, keyring, Infisical)
Input validation
Dependency security
File operations security
Command execution security

遵循本仓库的实践（来自

pyproject.toml

）：

python

undefined

2. Version Pinning Strategy

/// script

—

requires-python = ">=3.11"

—

dependencies = [

—

"httpx>=0.27.0", # 兼容的最低版本

—

"rich>=13.0.0", # 经过验证的稳定版本

—

"ansible>=11.1.0", # 匹配项目要求

—

]

—

///

Following this repository's approach (from

pyproject.toml

python

undefined


**固定级别：**

- `>=X.Y.Z` - 最低版本（灵活性最高）
- `~=X.Y.Z` - 兼容版本（仅接受补丁更新）
- `==X.Y.Z` - 精确版本（限制最严格）

查看[reference/dependency-management.md](reference/dependency-management.md)。

/// script

3. 团队标准

requires-python = ">=3.11"

—

dependencies = [

—

"httpx>=0.27.0", # Minimum version for compatibility

—

"rich>=13.0.0", # Known good version

—

"ansible>=11.1.0", # Match project requirements

—

]

—

///

—


**Pinning levels:**

- `>=X.Y.Z` - Minimum version (most flexible)
- `~=X.Y.Z` - Compatible release (patch updates only)
- `==X.Y.Z` - Exact version (most strict)

See [reference/dependency-management.md](reference/dependency-management.md).

文件命名：

bash

check_cluster_health.py    # ✅ 描述性强，采用蛇形命名法
validate_template.py       # ✅ 以动作导向命名
cluster.py                 # ❌ 过于笼统

Shebang写法：

python

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

3. Team Standards

--quiet参数会抑制uv自身的输出

File naming:

bash

check_cluster_health.py    # ✅ Descriptive, snake_case
validate_template.py       # ✅ Action-oriented
cluster.py                 # ❌ Too generic

Shebang pattern:

python

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


**文档模板：**

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

--quiet suppresses uv's own output

/// script

—

requires-python = ">=3.11"

—

dependencies = []

—

///


**Documentation template:**

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

""" 检查Proxmox集群健康状态

用途：cluster-monitoring 团队：infrastructure 作者：devops@spaceships.work

使用方法： python check_cluster_health.py [--node NODE] [--json]

示例： python check_cluster_health.py --node foxtrot python check_cluster_health.py --json """

undefined

/// script

4. 错误处理模式

requires-python = ">=3.11"

—

dependencies = []

—

///

—

""" Check Proxmox cluster health

Purpose: cluster-monitoring Team: infrastructure Author: devops@spaceships.work

Usage: python check_cluster_health.py [--node NODE] [--json]

Examples: python check_cluster_health.py --node foxtrot python check_cluster_health.py --json """

undefined

遵循本仓库中的Ansible最佳实践：

python

import sys
import subprocess

def run_command(cmd: str) -> str:
    """执行命令并进行适当的错误处理"""
    try:
        result = subprocess.run(
            cmd.split(),
            capture_output=True,
            text=True,
            check=True
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"错误：命令执行失败：{cmd}", file=sys.stderr)
        print(f"  {e.stderr}", file=sys.stderr)
        sys.exit(1)
    except FileNotFoundError:
        print(f"错误：未找到命令：{cmd.split()[0]}", file=sys.stderr)
        sys.exit(1)

查看patterns/error-handling.md。

4. Error Handling Patterns

5. 测试模式

Following Ansible best practices from this repository:

python

import sys
import subprocess

def run_command(cmd: str) -> str:
    """Execute command with proper error handling"""
    try:
        result = subprocess.run(
            cmd.split(),
            capture_output=True,
            text=True,
            check=True
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Error: Command failed: {cmd}", file=sys.stderr)
        print(f"  {e.stderr}", file=sys.stderr)
        sys.exit(1)
    except FileNotFoundError:
        print(f"Error: Command not found: {cmd.split()[0]}", file=sys.stderr)
        sys.exit(1)

See patterns/error-handling.md.

内联测试（适用于简单脚本）：

python

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

5. Testing Patterns

/// script

—

requires-python = ">=3.11"

—

dependencies = []

—

///

Inline testing (for simple scripts):

python

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

def validate_ip(ip: str) -> bool: """验证IP地址格式""" import re pattern = r'^(\d{1,3}.){3}\d{1,3}$' return bool(re.match(pattern, ip))

/// script

内联测试

requires-python = ">=3.11"

—

dependencies = []

—

///

—

def validate_ip(ip: str) -> bool: """Validate IP address format""" import re pattern = r'^(\d{1,3}.){3}\d{1,3}$' return bool(re.match(pattern, ip))

if name == "main": import sys

# 如果传入--test参数则运行测试
if len(sys.argv) > 1 and sys.argv[1] == "--test":
    assert validate_ip("192.168.1.1") == True
    assert validate_ip("256.1.1.1") == False
    print("所有测试通过！")
    sys.exit(0)

# 正常执行逻辑
print(validate_ip("192.168.3.5"))


查看[workflows/testing-strategies.md](workflows/testing-strategies.md)。

Inline tests

何时不适合使用单文件脚本

if name == "main": import sys

# Run tests if --test flag provided
if len(sys.argv) > 1 and sys.argv[1] == "--test":
    assert validate_ip("192.168.1.1") == True
    assert validate_ip("256.1.1.1") == False
    print("All tests passed!")
    sys.exit(0)

# Normal execution
print(validate_ip("192.168.3.5"))


See [workflows/testing-strategies.md](workflows/testing-strategies.md).

查看anti-patterns/when-not-to-use.md获取详细说明。

当出现以下情况时，应使用标准项目而非单文件脚本：

❌ 脚本代码超过500行
❌ 需要多个模块/文件
❌ 需要复杂的配置管理
❌ 需要打包/分发
❌ 多个脚本共享库代码
❌ 开发Web应用或长期运行的服务

示例 - 过于复杂不适合单文件：

python

undefined

When NOT to Use Single-File Scripts

这应该是一个uv项目，而非脚本：

—

- 15个以上依赖

—

- 数据库模型

—

- API路由

—

- 后台任务

—

- 配置管理

—

- 多环境支持

See anti-patterns/when-not-to-use.md for details.

Use a proper project instead when:

❌ Script exceeds 500 lines
❌ Multiple modules/files needed
❌ Complex configuration management
❌ Requires packaging/distribution
❌ Shared library code across multiple scripts
❌ Web applications or long-running services

Example - Too Complex for Single File:

python

undefined

undefined

This should be a uv project, not a script:

常见模式

- 15+ dependencies

—

- Database models

—

- API routes

—

- Background workers

—

- Configuration management

—

- Multiple environments

—

undefined

查看模式指南获取完整示例：

CLI应用 - Typer、Click、argparse使用模式
API客户端 - httpx、requests、认证方式
数据处理 - Polars、pandas、数据分析
系统自动化 - psutil、subprocess、系统管理

Common Patterns

CI/CD集成

—

GitHub Actions

See pattern guides for complete examples:

CLI Applications - Typer, Click, argparse patterns
API Clients - httpx, requests, authentication
Data Processing - Polars, pandas, analysis
System Automation - psutil, subprocess, system admin

yaml

name: Run Health Checks

on:
  schedule:
    - cron: '0 */6 * * *'  # 每6小时执行一次

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Check cluster health
        run: |
          uv run --script tools/check_cluster_health.py --json
        env:
          PROXMOX_TOKEN: ${{ secrets.PROXMOX_TOKEN }}

CI/CD Integration

GitLab CI

GitHub Actions

—

yaml

name: Run Health Checks

on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Check cluster health
        run: |
          uv run --script tools/check_cluster_health.py --json
        env:
          PROXMOX_TOKEN: ${{ secrets.PROXMOX_TOKEN }}

yaml

cluster-health:
  image: ghcr.io/astral-sh/uv:python3.11-bookworm-slim
  script:
    - uv run --script tools/check_cluster_health.py
  only:
    - schedules

查看workflows/ci-cd-integration.md。

GitLab CI

可用工具

—

脚本验证

yaml

cluster-health:
  image: ghcr.io/astral-sh/uv:python3.11-bookworm-slim
  script:
    - uv run --script tools/check_cluster_health.py
  only:
    - schedules

See workflows/ci-cd-integration.md.

bash

undefined

Tools Available

验证PEP 723元数据

Script Validation

—

bash

undefined

./tools/validate_script.py script.py

Validate PEP 723 metadata

输出：

—

✓ 有效的PEP 723元数据

—

✓ 指定了Python版本

—

✓ 依赖格式正确

./tools/validate_script.py script.py

undefined

Output:

脚本转换

✓ Valid PEP 723 metadata

—

✓ Python version specified

—

✓ Dependencies properly formatted

—

undefined

bash

undefined

Script Conversion

将基于requirements.txt的脚本转换为uv格式

bash

undefined

./tools/convert_to_uv.py old_script.py

Convert requirements.txt-based script to uv

生成：

—

- 包含内联依赖的old_script_uv.py

—

- 保留原始脚本

./tools/convert_to_uv.py old_script.py

undefined

Creates:

进阶学习

- old_script_uv.py with inline dependencies

—

- Preserves original script

—

undefined

如需深入了解：

Progressive Disclosure

参考文档

For deeper knowledge:

PEP 723规范 - 完整的内联元数据规范
依赖管理 - 版本固定策略
安全模式 - 密钥管理、验证、输入清理

Reference Documentation

模式指南

PEP 723 Specification - Complete inline metadata spec
Dependency Management - Version pinning strategies
Security Patterns - Secrets, validation, input sanitization

CLI应用 - Typer、Click、argparse使用模式
API客户端 - httpx、requests、认证方式
数据处理 - Polars、pandas、数据分析
系统自动化 - psutil、subprocess、系统管理
错误处理 - 异常处理、日志

注意： 可通过上方的常见模式部分快速访问这些指南。

Pattern Guides

实战示例

CLI Applications - Typer, Click, argparse patterns
API Clients - httpx, requests, authentication
Data Processing - Polars, pandas, analysis
System Automation - psutil, subprocess, system admin
Error Handling - Exception handling, logging

Note: See Common Patterns section above for quick access to these guides.

NetBox API客户端 - 生产就绪的API客户端，集成Infisical、验证、错误处理和Rich输出
集群健康检查器 - 生产就绪的监控脚本，集成Typer、Rich和JSON输出

Working Examples

反模式

NetBox API Client - Production-ready API client with Infisical, validation, error handling, and Rich output
Cluster Health Checker - Production-ready monitoring script with Typer, Rich, and JSON output

何时不使用 - 你需要标准项目的信号
常见错误 - 陷阱及规避方法

Anti-Patterns

工作流

When NOT to Use - Signs you need a proper project
Common Mistakes - Pitfalls and how to avoid them

团队采用 - 在团队中推广uv脚本
CI/CD集成 - GitHub Actions、GitLab CI
测试策略 - 内联测试、pytest集成

Workflows

Related Skills

快速参考

—

Shebang选项

Ansible Best Practices - Many Ansible modules could be standalone uv scripts
Proxmox Infrastructure - Validation tools use this pattern
NetBox + PowerDNS Integration - API interaction scripts

python

undefined

Quick Reference

标准脚本执行

Shebang Options

—

python

undefined

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

Standard script execution

静默模式（抑制uv输出）

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

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

Quiet mode (suppress uv output)

指定Python版本

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

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

undefined

With Python version

常见依赖

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

undefined

python

undefined

Common Dependencies

CLI应用

python

undefined

"typer>=0.9.0" # 现代CLI框架 "click>=8.0.0" # 替代CLI框架 "rich>=13.0.0" # 富文本与格式化

CLI applications

API客户端

"typer>=0.9.0" # Modern CLI framework "click>=8.0.0" # Alternative CLI framework "rich>=13.0.0" # Rich text and formatting

"httpx>=0.27.0" # 现代异步HTTP客户端 "requests>=2.31.0" # 传统HTTP客户端

API clients

数据处理

"httpx>=0.27.0" # Modern async HTTP client "requests>=2.31.0" # Traditional HTTP client

"polars>=0.20.0" # 高性能数据框库 "pandas>=2.0.0" # 传统数据框库

Data processing

基础设施

"polars>=0.20.0" # Fast dataframe library "pandas>=2.0.0" # Traditional dataframe library

"ansible>=11.1.0" # 自动化工具（来自本仓库） "infisical-python>=2.3.3" # 密钥管理工具（来自本仓库）

Infrastructure

系统自动化

"ansible>=11.1.0" # Automation (from this repo) "infisical-python>=2.3.3" # Secrets (from this repo)

"psutil>=5.9.0" # 系统监控工具

undefined

System automation

元数据模板

"psutil>=5.9.0" # System monitoring

undefined

python

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

Metadata Template

/// script

—

requires-python = ">=3.11"

—

dependencies = [

—

# 在此添加依赖

—

]

—

///

python

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

""" 单行描述

用途：说明用途团队：团队名称作者：email@example.com

使用方法： python script.py [OPTIONS]

示例： python script.py --help """

undefined

/// script

最佳实践总结

requires-python = ">=3.11"

—

dependencies = [

—

# Add dependencies here

—

]

—

///

—

""" One-line description

Purpose: describe-purpose Team: team-name Author: email@example.com

Usage: python script.py [OPTIONS]

Examples: python script.py --help """

undefined

始终指定Python版本 -
```
requires-python = ">=3.11"
```
合理固定依赖版本 - 工具类脚本使用
```
>=X.Y.Z
```
在文档字符串中添加元数据 - 将团队信息、用途和作者信息放在模块文档字符串中
添加完整的文档字符串 - 说明用途、使用方法和示例
优雅处理错误 - 使用try/except并给出清晰提示
验证输入 - 处理前检查参数
使用静默模式 - 生产脚本添加
```
--quiet
```
参数
保持聚焦 - 单文件实现单一功能
内联测试 - 添加
```
--test
```
参数进行简单验证
安全管理密钥 - 切勿硬编码，使用环境变量或密钥环

Best Practices Summary

—

Always specify Python version -
```
requires-python = ">=3.11"
```
Pin dependencies appropriately - Use
```
>=X.Y.Z
```
for utilities
Add metadata in docstrings - Put team info, purpose, and author in module docstring
Include comprehensive docstrings - Document purpose, usage, and examples
Handle errors gracefully - Use try/except with clear messages
Validate inputs - Check arguments before processing
Use quiet mode -
```
--quiet
```
flag for production scripts
Keep it focused - Single file, single purpose
Test inline - Add
```
--test
```
flag for simple validation
Secure secrets - Never hardcode, use env vars or keyring

—