- 越来越多的项目开始使用pyproject.toml来替代原本的setup.py进行包管理，以下是一个包含了讲解信息的示例文件
- 本实例使用setuptools作为其中的构建工具，它的逻辑最贴近setup.py。其他工具的介绍可以参考各工具官方文档。
# toml风格文件的完整语法详见： https://toml.io/cn/v1.0.0
# 项目使用的构建系统，支持setuptools、Hatchling、Flit、PDM、poetry等
# poetry使用介绍： https://python-poetry.org/docs/basic-usage/
# setuptools使用介绍: https://setuptools.pypa.io/en/latest/userguide/quickstart.html
[build-system]
# setuptools-scm是一个自动版本管理工具，可以自动从git、hg、bzr等版本控制系统中获取版本信息，会自动将受SCM管理的文件添加到sdist中，需要手动排除多余文件(可以使用MANIFEST.in)
requires = ["setuptools", "setuptools-scm"]
# 根据每个构建工具的介绍，设置对应的backend路径
build-backend = "setuptools.build_meta"
# 打包项目相关内容
[project]
# 打包后的文件名前缀,并不会影响最终安装到环境中的包名
name = "csr_package_example"
# 使用基础的指定版本号写法
# version = "1.0.0"
# 项目的依赖列表，基础的写法是将依赖在当前文件中列出来，并指定版本号
# dependencies = [
# "pyyaml",
# "requests>=2.26.0",
# "pydantic<=2.6.0",
# ]
# dynamic表示该字段通过动态方式生成，而不是直接直接写死一个值
# 使用动态方式指定version，setuptools_scm支持直接通过git commit id来生成版本号，需要在下方增加一句 [tool.setuptools_scm]
dynamic = ["version", "dependencies", "optional-dependencies"]
# 项目描述信息
description = "日志、文件、路径等通用功能的封装"
# 项目要求的python版本
requires-python = ">= 3.10"
# 项目的可选依赖，安装时使用 pip install 'csr_ddd[pytest,flask]' 这种方式安装(加单引号避免命令行解析错误)
# 使用直接写明可选依赖的方式
# [project.optional-dependencies]
# test = ["pytest","allure-pytest"]
# dev = ["flask>=2.0"]
# 命令行入口配置
# 在安装后会创建一个名字为cli-name的可执行文件，支持在命令行中通过cli-name来调用项目中的目标函数
# 相当于执行了 from csr_package_example.__main__ import cli; cli()两句python语句
[project.scripts]
cli-name = "csr_package_example.__main__:cli"
# 动态生成version的配置
[tool.setuptools_scm]
[tool.setuptools]
# 工具默认include-package-data为true，表示会自动将项目中的数据文件打包到安装包中
# 注意！由于增加了setuptools-scm，所以本地未提交的文件默认不会被包含在打包数据内
# 判断一个文件是否添加到打包whl中的判断逻辑如下
# (not exclude-package-data) and ((include-package-data and MANIFEST.in) or package-data)
# 详细介绍可以参考： https://setuptools.pypa.io/en/latest/userguide/datafiles.html
# include-package-data = false
# 用于指定要将哪些资源文件打包到项目中
# 注意，要设置include-package-data = false之后，这部分内容才有意义，否则项目中的数据都会被自动包含
[tool.setuptools.package-data]
# 表示从全部目录下，打包ini文件
# "*" = ["*.ini"]
# 表示从src/csr_package_example/inner_data目录下(不包含子目录)，额外打包yaml文件
# 支持用*进行通配
# csr_package_example = ["inner_data/*.yaml"]
# 也可以写成如下方式，用.作为多级目录的分割，但此方式的包名部分不支持*通配
# "csr_package_example.inner_data" = ["*.yaml"]
# 用于指定在打包时要排除哪些资源文件，排除的优先级高于include-package-data和package-data
# 具体写法和规则与package-data一致
[tool.setuptools.exclude-package-data]
# 表示从csr_package_example目录下(不包含子目录)中排除所有ini文件
csr_package_example = ["*.ini"]
# 动态从文件中读取依赖列表的配置，跟pip一样的解析方式，每行作为一个依赖，并且会忽略空行和注释行
# 支持多个文件组合，会按照文件顺序读取，合并依赖
[tool.setuptools.dynamic]
dependencies = { file = ["requirements.txt"] }
# 可选依赖也支持从文件中读取，解析规则与基础依赖一致
optional-dependencies.dev = { file = ["dev-requirements.txt", "extra_requirements.txt"] }
optional-dependencies.test = { file = ["test-requirements.txt"] }