零基础到发布:手把手教你创建并分发 Python 自定义库
作为程序员，我们经常依赖各种外部库来解决不同的问题。这些库由技术娴熟的开发者创建，为我们提供了节省时间和精力的解决方案。但你是否曾想过：“我也能创建属于自己的自定义库吗？”答案是肯定的！本文将为你详细介绍实现这一目标的必要步骤，无论你是专业开发者还是初学者，从代码编写和结构设计到文档编写和发布分发，本指南都将一一涵盖。
创建库的分步指南
第一步：初始化你的项目
首先，为你的项目创建一个根目录：
multiples_library/
第二步：为你的包创建目录
接下来，在项目根目录下创建你的包目录：
multiples_library/
└── multiples/
第三步：添加 init.py
现在，在你的包目录下添加 __init__.py 文件。该文件是 Python 判断目录为包的主要标志，可以包含初始化代码，并在包或其模块被导入时自动执行。
multiples_library/
└── multiples/
└── __init__.py
第四步：添加模块
接下来，需要在包目录下添加模块。模块通常包含类和函数。建议为每个模块起一个有意义的名字以描述其用途。
multiples_library/
│
└── multiples/
├── __init__.py
├── is_multiple_of_two.py
└── is_multiple_of_five.py
第五步：编写模块内容
在这一步，你将定义每个模块的具体功能。例如：
模块：is_multiple_of_two.py
def is_multiple_of_two(number):
"""检查一个数字是否为2的倍数。"""
return number % 2 == 0
模块：is_multiple_of_five.py
def is_multiple_of_five(number):
"""检查一个数字是否为5的倍数。"""
return number % 5 == 0
第六步：添加 setup.py
接下来，在你的包目录下添加 setup.py 文件。
multiples_library/
│
├── multiples/
│ ├── __init__.py
│ ├── is_multiple_of_two.py
│ └── is_multiple_of_five.py
│
└── setup.py
该文件包含有关你的包的元数据，如名称、依赖、作者、版本、简介等，还定义了要包含的模块以及构建和安装包的相关指令。
示例：setup.py
from setuptools import setup, find_packages
setup(
name='multiples_library', # 替换为你的包名
version='0.1.0',
packages=find_packages(),
install_requires=[
# 在此处列出依赖项
],
author='Your name',
author_email='Your e-mail',
description='一个用于检查2和5倍数的库。',
classifiers=[
'Programming Language :: Python :: 3',
'License :: OSI Approved :: MIT License', # 许可证类型
'Operating System :: OS Independent',
],
python_requires='>=3.6',
)
第七步：添加测试和其他文件（可选）
这一步并非必须，但如果你希望构建一个高质量、无错误的专业库，建议这样做。此时，项目结构大致如下：
multiples_library/
│
├── multiples/
│ ├── __init__.py
│ ├── is_multiple_of_two.py
│ └── is_multiple_of_five.py
│
├── tests/
│ ├── __init__.py
│ ├── test_is_multiple_of_two.py
│ └── test_is_multiple_of_five.py
│
├── docs/
├── LICENSE.txt
├── CHANGES.txt
├── README.md
├── setup.py
└── requirements.txt
下面对根目录下这些可选文件和文件夹的用途做简要说明：
- tests/
- ：包含库的测试用例，确保库按预期运行。
- docs/
- ：存放库的文档。
- LICENSE.txt
- ：说明他人使用你代码的许可条款。
- CHANGES.txt
- ：记录库的更新变更。
- README.md
- ：包含包简介和安装说明。
- requirements.txt
- ：列出库所需的所有外部依赖，可通过 pip install -r requirements.txt 一次性安装。
这些文件和文件夹的作用都非常直观，稍加了解即可明白其用途。这里我想补充说明一下 tests 目录的使用。
tests/ 目录
你可以选择在项目根目录（如 multiples_library）下或包目录（如 multiples）下添加 tests 目录。个人建议放在根目录下，有助于代码模块化。
编写测试用例有多种库可供选择。这里以最常用且我个人最喜欢的“unittest”为例。
is_multiple_of_two 的单元测试
测试案例存放于
test_is_multiple_of_two.py 文件：
import unittest
import sys
import os
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from multiples.is_multiple_of_two import is_multiple_of_two
class TestIsMultipleOfTwo(unittest.TestCase):
def test_is_multiple_of_two(self):
self.assertTrue(is_multiple_of_two(4))
if __name__ == '__main__':
unittest.main()
is_multiple_of_five 的单元测试
测试案例存放于
test_is_multiple_of_five.py 文件：
import unittest
import sys
import os
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from multiples.is_multiple_of_five import is_multiple_of_five
class TestIsMultipleOfFive(unittest.TestCase):
def test_is_multiple_of_five(self):
self.assertTrue(is_multiple_of_five(75))
if __name__ == '__main__':
unittest.main()
上述单元测试非常直观，但我再解释两个函数以便理解：
- self.assertTrue(expression)
- 检查表达式是否为 True，只有为 True 时测试通过。
- unittest.main()
- 用于运行文件中定义的所有测试用例。
第八步：通过 PyPI 分发你的包
为让他人方便地获取你的库，你可以将其上传至 PyPI。分发步骤如下：
- 在 PyPI 注册账号并开启双重验证。
- 创建 API 令牌，为其命名并选择作用范围为“整个账户（Entire account）”，复制保存该令牌（只显示一次）。
- 创建 .pypirc 文件。
- MacOS/Linux：打开终端，输入：cd ~
touch .pypirc - Windows：打开命令行，输入：cd %USERPROFILE%
type NUL > .pypirc - 编辑 .pypirc 文件，粘贴以下配置：
- [distutils]
index-servers =
pypi
[pypi]
username = __token__
password = pypi-<你的API令牌> - 注意：不要忘记在 API 令牌前加上 pypi- 前缀。
- 确保项目根目录下有 setup.py 文件。生成分发文件：
- python3 setup.py sdist bdist_wheel
- 安装上传工具 twine：
- pip install twine
- 使用 twine 上传你的包：
- twine upload dist/*
第九步：安装和使用你的库
你可以通过如下命令安装库：
pip install [your-package]
例如：
pip install multiples_library
现在你可以这样使用库：
from multiples.is_multiple_of_five import is_multiple_of_five
from multiples.is_multiple_of_two import is_multiple_of_two
print(is_multiple_of_five(10)) # 输出 True
print(is_multiple_of_two(11)) # 输出 False
总结
简而言之，创建一个 Python 库既有趣又实用，将它分发出去还能帮助他人。本文努力以清晰的方式涵盖了创建 Python 库所需的全部内容。如果你在操作过程中遇到任何问题或困惑，欢迎在评论区留言提问。