从现有Python项目创建并发布PyPI包教程-Python教程-PHP中文网

从现有Python项目创建并发布PyPI包教程

花韻仙語

发布： 2025-08-06 21:44:23

原创

385人浏览过

从现有Python项目创建并发布PyPI包教程

本教程详细指导如何将现有Python项目打包并发布到PyPI。内容涵盖项目目录结构调整、使用pyproject.toml配置包元数据与构建系统、生成分发包，以及最终通过twine工具上传至PyPI的完整流程。旨在帮助开发者高效地将Python应用或库分享给社区，实现便捷的pip install安装。

pypi（python package index）是python社区的官方第三方软件包仓库，通过将您的项目发布到pypi，其他用户便能使用pip install your-package-name命令轻松安装和使用您的代码。本教程将引导您完成从项目准备到最终发布的每一个关键步骤。

1. 项目结构准备与规范

为了确保您的Python项目能够正确地被打包，建议遵循标准的项目结构。最推荐的做法是将所有可安装的源代码放置在一个专用的源目录（通常命名为src）中。

建议的项目结构示例：

your-project-name/
├── src/
│   └── your_package_name/
│       ├── __init__.py
│       └── your_module.py
├── tests/
│   └── test_your_module.py
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

登录后复制

关键点：

src/ 目录： 包含您实际希望作为PyPI包发布的Python源代码。这样做的好处是，可以清晰地区分源代码与项目中的其他文件（如测试文件、文档、构建脚本等），避免不必要的非源代码文件被打包进去。
your_package_name/： 这是您的Python包的顶级模块名，通常与您的项目名称保持一致或相似。其中必须包含一个__init__.py文件，即使是空的，它也能将该目录标记为一个Python包。
排除非必需文件： 像测试文件（tests/）、开发脚本、大型数据集等不应包含在最终的PyPI分发包中。pyproject.toml的配置和src目录的使用有助于自然地排除这些文件。

2. 配置 pyproject.toml 文件

pyproject.toml是现代Python打包的标准配置文件，它取代了传统的setup.py和setup.cfg，用于定义项目的元数据、构建系统以及依赖关系。

立即学习“Python免费学习笔记（深入）”；

在项目根目录下创建pyproject.toml文件，并添加以下基本内容：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package-name" # 您的包在PyPI上的名称
version = "0.1.0" # 包的版本号，遵循语义化版本（Semantic Versioning）
authors = [
  { name="Your Name", email="your.email@example.com" },
]
description = "A short description of your project." # 简短描述
readme = "README.md" # 指向您的README文件
requires-python = ">=3.8" # 兼容的Python版本
keywords = ["ai", "assistant", "debug"] # 关键词，有助于搜索
classifiers = [ # 分类器，描述您的项目
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha", # 开发状态
    "Intended Audience :: Developers",
]
dependencies = [ # 运行时依赖，pip会自动安装
    "requests>=2.25.1",
    "numpy",
    # 其他依赖...
]

[project.urls]
Homepage = "https://github.com/your-username/your-project-name" # 项目主页
"Bug Tracker" = "https://github.com/your-username/your-project-name/issues" # Bug追踪

[project.optional-dependencies] # 可选依赖，例如开发或测试依赖
dev = ["pytest", "twine", "build"]

[tool.setuptools.packages.find]
where = ["src"] # 告诉setuptools在src目录下查找包

登录后复制

pyproject.toml关键字段说明：

[build-system]： 定义了构建包所需的工具和后端。setuptools和wheel是常用的构建工具。
[project]： 包含包的所有元数据。
- name：您的包在PyPI上的唯一名称。
- version：包的版本号，每次发布新版本时都需要更新。
- authors：作者信息。
- description：包的简短描述。
- readme：指向您的README.md文件，PyPI会显示其内容。
- requires-python：指定包兼容的Python版本范围。
- keywords：有助于用户搜索您的包。
- classifiers：标准化的字符串，描述您的项目，例如许可证、操作系统、Python版本等。可以在PyPI官方文档中找到完整的分类器列表。
- dependencies：列出您的项目运行所需的第三方库及其版本要求。
[project.urls]： 提供项目相关的链接，如主页、bug追踪等。
[project.optional-dependencies]： 定义可选的依赖项，例如仅在开发或测试阶段需要的库。
[tool.setuptools.packages.find]： 如果您使用了src目录结构，此配置告诉setuptools在src目录中查找包。

3. 构建分发包

在配置好pyproject.toml之后，您可以使用build模块来生成分发包。

首先，确保您安装了build模块：

pip install build

登录后复制

然后，在您的项目根目录（pyproject.toml所在的目录）下运行构建命令：

python -m build

登录后复制

执行此命令后，会在项目根目录下生成一个名为dist/的目录。该目录中会包含两个文件：

wxPython 2.8 Application Development Cookbook英文pdf版

在今天的桌面应用世界上有大量的奖励，以便能够开发应用程序，可以运行在多个环境。目前，有一种跨平台框架可供选择的Python开发桌面应用程序屈指可数。 wxPython的就是这样的一个跨平台的GUI工具包的Python编程语言。它允许Python程序员创建一个完整的，功能强大的图形用户界面的程序，简单，方便。 wxPython的代码风格，改变了多年来不少，并得到更多Python的。例子，你会发现这本书是对不断更新，反映在风格上的变化。本书提供最新的书，快速创建健壮的，可靠，可重复使用的wxPython应用

查看详情

.whl文件（Wheel）：这是一个预编译的二进制分发包，可以直接安装，通常是首选的安装方式。
.tar.gz文件（Source Distribution, sdist）：这是一个源代码分发包，包含您的项目源代码和其他元数据，可以在目标机器上进行编译和安装。

4. 上传到PyPI

在上传之前，您需要一个PyPI账户。如果还没有，请前往 PyPI官网注册。为了安全起见，建议使用API Token进行认证，而不是直接使用用户名和密码。

创建API Token： 登录PyPI账户后，导航到 "Account settings" -> "API tokens"，创建一个新的API Token，并务必保存好，因为它只会显示一次。
安装twine： twine是一个用于安全上传Python包到PyPI的工具。
```
pip install twine
```
登录后复制
上传包： 在项目根目录，使用twine上传dist/目录中的所有文件：
```
twine upload dist/*
```
登录后复制
twine会提示您输入PyPI用户名和密码。对于API Token，用户名输入__token__，密码则输入您之前保存的API Token（通常以pypi-开头）。

如果您想先测试上传过程而不发布到正式的PyPI，可以使用TestPyPI：
```
twine upload --repository testpypi dist/*
```
登录后复制
TestPyPI的注册和API Token创建过程与正式PyPI类似，但它们是独立的。

成功上传后，您的包就可以通过pip install your-package-name命令进行安装了。

注意事项

版本管理： 每次发布新版本时，务必更新pyproject.toml中的version字段。遵循语义化版本（Semantic Versioning）规则（MAJOR.MINOR.PATCH），例如1.0.0、1.0.1、1.1.0等。
许可证（License）： 在您的项目中包含一个许可证文件（如LICENSE），并在pyproject.toml中通过classifiers指定，这对于开源项目至关重要。
README.md： 提供清晰、详细的README.md文件，包含项目简介、安装指南、使用示例、贡献方式等，这会极大地提升您项目的可发现性和可用性。
依赖项： 确保pyproject.toml中的dependencies列表准确无误，只包含运行时必需的依赖，并指定合适的版本范围。
测试： 在发布之前，务必对您的包进行充分的测试，确保其功能完善且稳定。
虚拟环境： 在开发和打包过程中，始终使用虚拟环境，以避免包依赖冲突。

总结

将Python项目打包并发布到PyPI是一个相对直接的过程，但需要注意一些细节。通过遵循本教程中概述的步骤——规范项目结构、精确配置pyproject.toml、使用build工具构建分发包，以及利用twine安全上传——您将能够成功地将您的Python项目发布到PyPI，使其可供全球Python社区轻松安装和使用。这不仅是分享您的工作成果的有效方式，也是对开源社区的重要贡献。

以上就是从现有Python项目创建并发布PyPI包教程的详细内容，更多请关注php中文网其它相关文章！