使用者:Xyy23330121/Python/發布自己的模塊

讀者可能會想要分享自己編寫的模塊。在安裝第三方模塊時，pip 在 PyPI（The Python Package Index） 上查詢讀者給出的模塊名，從而安裝了對應的第三方模塊。若讀者想要發布自己編寫的模塊，也應該把模塊發布到 PyPI 上面去。

本頁面將講解如何發布自己的模塊。

發布模塊

發布 Python 模塊的方法有很多種，可以參閱相關的 文檔。這裡只講解一種。

一個待發布的模塊，一般具有以下的文件結構：

MyPackge/          #随便一个文件夹

    LICENSE.txt      #授权协议信息
    README.md        #说明信息。
    pyproject.toml   #安装时的配置
    
    src/             #模块内容
        MyModule/   #模块名
            __init__.py
            ...

可以看到，除了模塊內容之外，還需要三個文件。LICENSE.txt 和 README.md 很好理解，以下主要講解 pyproject.toml 的內容。

pyproject.toml

pyproject.toml 會包含安裝本模塊時所需的配置信息。為簡便起見，這裡直接將一個完整的示例放在下方：

#toml 在许多方面有类似 Python 的语法，比如注释前面也需要井号。

[build-system]
#安装模块时所使用的安装方式
#这里以使用 setuptools 包所提供的安装方式，来安装自定义模块为例。
#其它安装方式，参见 https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#declaring-the-build-backend
#setuptools 参见：https://pypi.org/project/setuptools/

#需要 >= 61.0 版本的 setuptools
requires = ["setuptools >= 61.0"]
build-backend = "setuptools.build_meta"

[project]
#模块的基本信息

#模块名称、版本、说明、readme文件位置
name = "MyModule"
version = "0.0.1"
description = "这是一个测试模块"
readme = "README.md"

#授权协议
license = {file = "LICENSE.txt"}
#也可以使用协议名称的方式来确认授权协议。
#license = {text = "MIT License"}

#关键词列表
#当其他人在PyPI搜索以下关键词时，PyPI会把你的模块加入到搜索结果中。
keywords = ["关键词1", "关键词2", "关键词3", "关键词4", "关键词5"]

#分类列表
#方便其它人在PyPI按分类筛选模板
#浏览 https://pypi.org/classifiers/ 以获取更多可能的分类，以下是分类示例
classifiers = [
  "Development Status :: 3 - Alpha",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python :: 3.12"
]

#作者列表和维护者列表
#一般要包含人名和电子邮箱地址。但也可以只包含人名，或者只包含电子邮箱地址。
authors = [
  {name = "作者1", email = "author1@example.com"},
  {name = "作者2", email = "author2@example.com"},
  {name = "作者3"},
  {email = "author4@example.com"},
]
maintainers = [
  {name = "维护者1", email = "maintainer1@example.com"}
]

#环境需求（可选）
#有的模块中可能会 import 来自其它模块的内容。这里要列出本模块所 import 的、并非 Python 内置模块的模块。
#如果不需要任何额外模块，可以不包含此项。
dependencies = [
  "numpy",
  "gidgethub[httpx]>4.0.0",
  "django>2.1; os_name != 'nt'",
  "django>2.0; os_name == 'nt'",
]
#所需的 Python 版本
requires-python = ">= 3.8"

[project.optional-dependencies]
#可选的环境需求（可选）
#如果在安装时使用了对应的选项，则会额外安装以下的模块。

#pip install MyModule[gui] 时，会额外安装的模块。
gui = ["tkinter"]

#pip install MyModule[cli] 时，会额外安装的模块。
cli = [
  "click",
]

[project.urls]
#模块相关的网页。（可选）
Homepage = "https://模块主页.com"
Documentation = "https://模块文档.readthedocs.org"
Repository = "https://github.com/exampleauthor/examplemodule.git"
Issues = "https://github.com/exampleauthor/examplemodule/issues"
Changelog = "https://github.com/exampleauthor/examplemodule/blob/master/CHANGELOG.md"

[project.scripts]
#当安装模块时，会注册的命令。（可选）
#以下内容代表：
#  在比如 cmd.exe 的程序中，执行 "runMyModule" 指令时，会在前台执行以下 python 代码：
#    from MyModule import 指令名
#    指令名()
runMyModule = "MyModule:指令名"

[project.gui-scripts]
#当安装模块时，会注册的命令。（可选）
#如果是 Windows 系统，以下内容代表：
#  在比如 cmd.exe 的程序中，执行 "runMyModule" 指令时，会在后台执行以下 python 代码：
#    from MyModule import 指令名2
#    指令名2()
#如果是其它系统，以下项目和 project.scripts 中的项目没区别。
run_module_gui = "MyModule:指令名2"

[project.entry-points."模块B.指令A"]
#本模块可以作为其它模块的插件
#如果安装本模块，在执行“模块B”中的“指令A”时，会替换为执行“MyModule”中的“指令名3”
excl = "MyModule:指令名3"
#更多使用方式，参见：
# 作为插件使用 https://setuptools.pypa.io/en/latest/userguide/entry_point.html#entry-points-for-plugins
# importlib 模块的文档

除使用 pyproject.toml 之外，還可以使用 setup.py 或 setup.cfg 來存儲模塊的安裝配置。參見：

• 快速入門（包含使用 setup.py 的內容）
• 用 setup.cfg 設置安裝配置

當前不建議使用 setup.py 或 setup.cfg 來存儲安裝配置。

打包模塊

要打包模塊，需要運行以下命令：

pip install --upgrade build

然後用類似以下指令的方式，移動到模塊文件夾下：

cd "MyPackage"

然後再執行以下指令：

python -m build

這些指令完成後，會生成類似以下的文件：

MyPackge/
    dist/
        example_package-0.0.1-py3-none-any.whl
        example_package-0.0.1.tar.gz

進行測試

在把模塊上傳到 PyPI 前，還需要對模塊進行最後一步測試：將模塊上傳到 TestPyPI。

生成 Token

為了模塊的安全，使得惡意用戶不可以私自改動讀者在 PyPI 上分享的內容，讀者將需要一個 token。讀者應該遵循以下的步驟：

• 在 https://test.pypi.org/account/register/ 中註冊一個帳戶。
• 在 https://test.pypi.org/manage/account/#api-tokens 中創建一個 token 並保存它。
  除了 token 第一次生成時，讀者無法在網頁中查到已生成的 token。除非讀者已經把 token 保存到本地，請不要關閉本步驟所打開的網頁。

上傳模塊

讀者可以使用 twine 模塊來上傳自己的模塊。先安裝 twine 模塊：

pip install --upgrade twine

然後用類似以下指令的方式，移動到模塊文件夾下：

cd "MyPackage"

然後再執行以下指令：

py -m twine upload --repository testpypi dist/*

測試模塊

將上傳的模塊安裝到電腦上：

pip install --index-url https://test.pypi.org/simple/ --no-deps MyModule

然後進行測試即可。

正式上傳

正式上傳的步驟和測試的步驟類似。首先生成 token：

• 在 https://pypi.org/account/register/ 中註冊一個帳戶。
• 在 https://pypi.org/manage/account/#api-tokens 中創建一個 token 並保存它。

然後用以下指令進行上傳即可：

py -m twine upload dist/*

編寫文檔

如果希望其他人使用自己的模塊，讀者應當給自己的模塊編寫一份文檔。這個文檔應該包含以下內容：

• 安裝方式 Installation
  包含各種系統應該如何安裝此模塊。一般情況下，僅包含一句pip install ModuleName。如果有可選項，還會包含pip install ModuleName[Option]等。
• 快速入門 Quick Start
  包含導入模塊，並使用模塊的一個基本功能的方法。
• 用戶指南 User Guide
  包含使用模塊更多功能的方法。
• 開發者指南 Developer Guide
  包含參與該模塊編寫開發時的要點。
• API 參考 API Reference
  包含模塊中一切函數、變量、類、類的方法、類的屬性等的具體信息。

發布文檔的常用方法是：

• 使用 github 博客頁，或者在 github 中用 Markdown 文件的方式編寫文檔。
• 發布到 readthedocs.io。
• 自己建立一個網站，在網站上發布文檔。