維基學院

用户:Xyy23330121/Python/发布自己的模块

< User: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 来存储安装配置。

打包模块

编辑

要打包模块，需要运行以下命令： 

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。读者应该遵循以下的步骤：

上传模块

编辑

读者可以使用 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：


然后用以下指令进行上传即可： 

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。
  • 自己建立一个网站，在网站上发布文档。
检索自“https://zh.wikiversity.org/w/index.php?title=User:Xyy23330121/Python/发布自己的模块&oldid=271191”