SuperAPI AI 工具集

pyproject-toml

编程与开发

查看项目

更新于 10-16 05:58

技能介绍

用途

本技能用于掌握 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 项目。除上述内容外,关于收费、价格、平台支持等事实暂未提供。