零基础到发布：手把手教你创建并分发 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文件，粘贴以下配置：