从零开始构建和发布Python库的完整指南
内容提要
本文是一份全面的指南，介绍了从头开始创建Python库、测试、文档化并最终发布到PyPI的整个过程。
延伸解读
为什么采用 src 目录结构
指南将库代码放在 src/datawizard/ 下，而不是直接放在项目根目录。这种布局能避免测试时意外导入本地未安装的包，强制测试针对已安装版本运行，更接近用户实际使用场景。同时，pyproject.toml 中通过 [tool.setuptools.packages.find] 指定 where = ["src"]，确保打包时只包含库代码，排除 tests 等目录。
pyproject.toml 如何统一打包配置
文章使用 pyproject.toml 集中管理构建系统、项目元数据、依赖和打包发现规则。其中 build-system 指定 setuptools 和 wheel，project 部分定义名称、版本、作者、许可证、分类器、关键词、依赖及 Python 版本要求。这种声明式配置替代了传统的 setup.py，使打包信息更清晰，也便于工具链统一读取。
持续集成与自动发布的衔接
指南分别配置了 CI 和发布工作流。CI 在 push 和 pull_request 时触发，使用矩阵策略在多个 Python 版本上运行 pytest，提前发现兼容性问题。发布工作流则在 GitHub Release 创建时触发，通过 build 构建分发包，并用 twine 上传到 PyPI，认证依靠仓库 secret 中的 PYPI_API_TOKEN。两者结合，让测试和发布都自动化。
文档托管与项目维护要点
文档使用 MkDocs 和 Material 主题，并通过 GitHub Actions 部署到 GitHub Pages，需在仓库设置中将 Pages 源设为 gh-pages 分支。维护方面，文章强调定期更新依赖、响应 issue 和 pull request、保持文档最新，并在每次发布新版本或修复 bug 时递增 pyproject.toml 中的版本号。这些步骤共同保证库的长期可用性。
Q&A
如何从头开始创建一个Python库？
首先创建一个新目录并设置虚拟环境，然后在src/datawizard/目录中编写库代码，最后配置打包信息和文档。
如何测试我的Python库？
可以使用pytest进行测试，首先安装pytest，然后创建测试文件并运行测试。
如何将Python库发布到PyPI？
安装build和twine，构建包后使用twine上传到PyPI，并确保创建PyPI账户和API令牌。
如何管理Python库的依赖关系？
创建requirements.txt文件列出开发依赖，并使用pip安装这些依赖。
如何创建Python库的文档？
使用MkDocs和Material主题创建文档，编写Markdown文件并使用mkdocs serve本地构建文档。
如何设置持续集成以测试我的Python库？
创建GitHub Actions工作流文件，配置测试步骤以在每次推送或拉取请求时自动运行测试。
