零基础到发布：手把手教你创建并分发 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。分发步骤如下：

1. 在 PyPI 注册账号并开启双重验证。

2. 创建 API 令牌，为其命名并选择作用范围为“整个账户（Entire account）”，复制保存该令牌（只显示一次）。

3. 创建 .pypirc 文件。

   • MacOS/Linux：打开终端，输入：

     cd ~
     touch .pypirc
     

   • Windows：打开命令行，输入：

     cd %USERPROFILE%
     type NUL > .pypirc
     

4. 编辑 .pypirc 文件，粘贴以下配置：

   [distutils]
   index-servers =
       pypi
   
   [pypi]
   username = __token__
   password = pypi-<你的API令牌>
   

   注意：不要忘记在 API 令牌前加上 pypi- 前缀。

5. 确保项目根目录下有 setup.py 文件。生成分发文件：

   python3 setup.py sdist bdist_wheel
   

6. 安装上传工具 twine：

   pip install twine
   

7. 使用 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 库所需的全部内容。如果你在操作过程中遇到任何问题或困惑，欢迎在评论区留言提问。