packaging-with-uv

使用 uv 打包与依赖管理指南 (Packaging and Dependency Management with uv Guide)

本指南为使用 uv 进行 Python 项目的依赖管理和打包（特别关注旨在发布到 PyPI 的项目，并以 coze-mcp-server 作为一个应用了许多这些原则的示例项目）提供规范和最佳实践。 uv 是一个非常快速的 Python 包安装器和解析器，旨在替代 pip 和 pip-tools 的部分功能。

参考：

• coze-mcp-server 项目中的 [pyproject.toml](mdc:pyproject.toml) 和 [uv.lock](mdc:uv.lock) (作为实际项目配置的示例)。
• coze-mcp-server [README.md](mdc:README.md) 中的安装说明 (展示了 uv 在实际使用中的一个场景)。

1. pyproject.toml 核心配置

[pyproject.toml](mdc:pyproject.toml) 是项目的核心配置文件，用于声明元数据、依赖项和构建系统。其在项目中的位置和基本作用可参考 项目结构指南 中关于配置文件的说明。

1.1. [project] 表

• name: 项目的规范名称，即在 PyPI 上发布的名称 (e.g., coze-mcp-server)。
• version: 项目版本号，遵循 PEP 440 (e.g., "0.0.4")。动态版本控制也是一种选择，但需谨慎。
• description: 项目的简短描述。
• readme: 指定 README 文件 (e.g., "README.md")。
• requires-python: 指定项目兼容的 Python 版本 (e.g., ">=3.8")。
• license: 指定许可证，例如 {text = "MIT License"} 或 {file = "LICENSE"}。
• authors / maintainers: 列出作者和维护者信息。
• dependencies: 列出项目运行所必需的核心依赖项，带有版本说明符 (e.g., fastapi >= 0.100.0, < 0.101.0)。
  • 尽量使用兼容版本 (~=), 范围版本 (>=, <) 或精确版本 (==) 来平衡灵活性和稳定性。
• [project.optional-dependencies]: 定义可选的依赖组，例如 dev, test。
  • coze-mcp-server 在 pyproject.toml 中定义了 dev 依赖。
  • 安装可选依赖：uv pip install .[dev]
  • 针对特定功能（如 CLI 工具）的可选依赖: 许多包（例如 mcp Python SDK）会通过可选依赖项提供额外功能。例如，如果一个包提供了命令行工具，它可能会通过一个名为 cli 的 "extra" 来提供。安装时可以使用 uv pip install package_name[cli]。
    • 参考 modelcontextprotocol/python-sdk 的 README ([mdc:https:/github.com/modelcontextprotocol/python-sdk/blob/main/README.md])，其中提到了 "standalone MCP development tools" (例如 mcp run, mcp dev)。这类工具通常就是通过类似 mcp[cli] 的方式安装的。开发者应查阅对应包的 pyproject.toml 或文档来确定可用的 "extras"。
• [project.urls]: 提供项目的相关链接，如 Homepage, Repository, Bug Tracker。
• [project.scripts]: (如果适用) 定义通过命令行可执行的脚本。对于 coze-mcp-server 这种通过 python -m 运行的包，可能不直接在这里定义，而是通过包的 __main__.py。
  • coze-mcp-server 的 README.md 中配置 Claude.app/Zed 时，使用了 python -m coze_mcp_server 或 uvx coze-mcp-server。
• classifiers: 提供 PyPI 分类器，帮助用户发现项目。