用途
本技能用于掌握 pyproject.toml,实现现代 Python 项目配置、构建系统、工具设置与依赖管理。当需要配置项目元数据(名称、版本、描述、作者)、依赖管理(核心与可选依赖)、构建配置(setuptools、hatch、flit、poetry、pdm)、工具配置(pytest、ruff、mypy、black、isort)、入口点(CLI 脚本与插件)以及包发现(源码目录配置)时使用本技能。资料说明:应避免用于需要 setup.py 的遗留项目(罕见,建议迁移)以及非 Python 项目。
主要能力
技能提供一份完整的 pyproject.toml 模板,覆盖以下配置区块:
- 构建系统:
[build-system]使用 setuptools,也列出 hatch、flit、poetry、pdm 等替代构建后端示例。 - 项目元数据:
[project]中的 name、version、description、readme、requires-python、license、authors、maintainers、keywords、classifiers;license 支持{text = "MIT"}、{file = "LICENSE"}、"MIT"等格式。 - 依赖:核心
dependencies与[project.optional-dependencies],支持版本约束写法(>=、范围>=1.24,<2.0、~=、==、无版本),并提供 dev、docs、viz、all 等可选依赖分组。 - 入口点:
[project.scripts]CLI 脚本、[project.gui-scripts]、[project.entry-points."..."]插件系统,附 click 实现示例。 - URLs:
[project.urls]的 Homepage、Documentation、Repository、Issues、Changelog。 - 包发现:
[tool.setuptools]的 src 布局与 flat 布局,[tool.setuptools.packages.find]包含/排除规则,[tool.setuptools.package-data]数据文件包含。 - 工具配置:
[tool.uv]、[tool.pytest.ini_options]、[tool.coverage.*]、[tool.ruff](lint、isort、format 子表)、[tool.mypy](含 overrides)、[tool.black]、[tool.isort]、[tool.bumpver]及[tool.bumpver.file_patterns]。
使用方式
技能以分节指南与完整示例形式给出配置写法,包含三种完整示例:数据处理库(data-processor)、网页抓取包(energy-scraper,含 scrapy、selenium、beautifulsoup4、aiohttp 与异步 pytest 配置)、workspace-hub 标准模板。使用步骤为:按模板填写各区块,通过 pip install my-project[dev] 等方式安装可选依赖组,通过 [project.scripts] 暴露命令行命令。资料给出最佳实践:推荐使用 >= 最小版本、范围约束或 ~= 兼容版本,避免 == 过严或完全不写版本导致冲突;可选依赖按用途分组(dev、docs、viz)。
适用场景
适用于需要统一管理打包、依赖、入口点与多工具配置的现代 Python 项目,包括数据加工库、网络抓取包,以及遵循 src 布局并在 pytest、ruff、mypy、coverage、bumpver 等工具中统一配置的工程化项目。
限制
资料明确说明不适用于需要 setup.py 的遗留项目和非 Python 项目。除上述内容外,关于收费、价格、平台支持等事实暂未提供。