关于发布Python库全过程总结和踩坑记录

写在前面#

兴致来了，打算做一个自己的Python工具库，发布到PyPi上，这样可以自己在生活工作的时候直接通过pip install来进行安装和使用。

我的库名最后决定为HandyToolsPy，也就是便捷工具库，里面包含了一些自己常用的工具函数和有趣的项目。

欢迎大家pip install食用。

如果有想加入这个库的好点子请告诉我，我会积极反馈并考虑加入其中。

1. 准备工作#

1.1 创建目录#

需要到一个空目录下，创建一个文件夹和setup.py、README.md、LICENSE文件。文件夹名就是库名，比如我创建的文件夹名就是HandyToolsPy。目录结构

1.2 目录功能介绍#

README.md即是库的说明文档，LICENSE是库的许可证，我选择的是GPL 3.0许可证。其他更多的许可证请至这里查看和使用。

setup.py即为你的库的管理工具，Python官网更喜欢使用.toml文件进行管理，但是我都捣鼓了一下，发现还是setup.py的形式比较方便，而且requests库的作者写了一个非常经典的模板，可以参考使用。

可以看到我在HandyToolsPy中创建了__init__.py、__version__.py、DataProcess.py、Translator.py四个文件，具体功能如下:

__init__.py
1. 将目录标记为Python包，这是它最基本的作用，它使得Python解释器知道该目录及其包含的文件应该被视为一个包.
2. 包的命名空间管理，__init__.py文件可以用来组织包的命名空间。通过在这个文件中导入函数、类或其他模块，你可以提供一个经过精心设计的对外接口，使得包的结构对用户更加透明。
__version__.py
1. 定义库的版本号，方便用户查看和更新。

另外两个文件即功能模块，就是这个库导入后的功能类或功能函数。

2. 开始#

2.1 许可证#

上传到Python Package Index的每个包都包含许可证，这一点很重要。这告诉用户安装你的软件包可以使用您的软件包的条款。

2.2 `setup.py`#

使用上一小节提供的模板即可，注意NAME和VERSION要分别对应你自己库的名称和版本号。

一个可能的setup.py文件如下:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

# Note: To use the 'upload' functionality of this file, you must:
#   $ pipenv install twine --dev

import io
import os
import sys
from shutil import rmtree

from setuptools import find_packages, setup, Command

# Package meta-data.
NAME = 'HandyToolsPy'
DESCRIPTION = 'Handypy is a multifunctional Python tool library, which aims to provide developers with a series of convenient practical tools and simplify daily programming tasks.Whether it is processing data, operating file systems, or network requests, Handypy can provide you with efficient and reliable solutions.'
URL = 'https://github.com/kimbleex/HandyToolsPy'
EMAIL = 'kimbleex@outlook.com'
AUTHOR = 'kimbleex'
REQUIRES_PYTHON = '>=3.6.0'
VERSION = '0.1.1'

# What packages are required for this module to be executed?
REQUIRED = [
    'pandas', 'googletrans',
]

# What packages are optional?
EXTRAS = {
    # 'fancy feature': ['django'],
}

# The rest you shouldn't have to touch too much :)
# ------------------------------------------------
# Except, perhaps the License and Trove Classifiers!
# If you do change the License, remember to change the Trove Classifier for that!

here = os.path.abspath(os.path.dirname(__file__))

# Import the README and use it as the long-description.
# Note: this will only work if 'README.md' is present in your MANIFEST.in file!
try:
    with io.open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
        long_description = '\n' + f.read()
except FileNotFoundError:
    long_description = DESCRIPTION

# Load the package's __version__.py module as a dictionary.
about = {}
if not VERSION:
    project_slug = NAME.lower().replace("-", "_").replace(" ", "_")
    with open(os.path.join(here, project_slug, '__version__.py')) as f:
        exec(f.read(), about)
else:
    about['__version__'] = VERSION


class UploadCommand(Command):
    """Support setup.py upload."""

    description = 'Build and publish the package.'
    user_options = []

    @staticmethod
    def status(s):
        """Prints things in bold."""
        print('\033[1m{0}\033[0m'.format(s))

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        try:
            self.status('Removing previous builds…')
            rmtree(os.path.join(here, 'dist'))
        except OSError:
            pass

        self.status('Building Source and Wheel (universal) distribution…')
        os.system('{0} setup.py sdist bdist_wheel --universal'.format(sys.executable))

        self.status('Uploading the package to PyPI via Twine…')
        os.system('twine upload dist/*')

        self.status('Pushing git tags…')
        os.system('git tag v{0}'.format(about['__version__']))
        os.system('git push --tags')

        sys.exit()


# Where the magic happens:
setup(
    name=NAME,
    version=about['__version__'],
    description=DESCRIPTION,
    long_description=long_description,
    long_description_content_type='text/markdown',
    author=AUTHOR,
    author_email=EMAIL,
    python_requires=REQUIRES_PYTHON,
    url=URL,
    packages=find_packages(exclude=["tests", "*.tests", "*.tests.*", "tests.*"]),
    # If your package is a single module, use this instead of 'packages':
    # py_modules=['mypackage'],

    # entry_points={
    #     'console_scripts': ['mycli=mymodule:cli'],
    # },
    install_requires=REQUIRED,
    extras_require=EXTRAS,
    include_package_data=True,
    license='MIT',
    classifiers=[
        # Trove classifiers
        # Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 3.6',
        'Programming Language :: Python :: 3.7',
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
        'Programming Language :: Python :: 3.10',
        'Programming Language :: Python :: 3.11',
        'Programming Language :: Python :: 3.12',
        'Programming Language :: Python :: Implementation :: CPython',
        'Programming Language :: Python :: Implementation :: PyPy',
    ],
    # $ setup.py publish support.
    cmdclass={
        'upload': UploadCommand,
    },
)

2.3 编写功能类#

在上述过程完成后，你可以在你的库文件夹下面编写你的功能类。

2.4 生成分发档案#

接着，需要生成库的分发档案，以便上传到 PyPI。

更新build，并使用它生成分发档案文件。

python -m pip install --upgrade build
python -m build

如果正常执行，会有大片输出，并在目录下生成dist和.egg-info目录 build

3. `PyPi`部分#

3.1 注册并认证#

至于如何注册账号，如何获取2FA认证获取发布权限，请自行学习，这里不再赘述。

完成后生成一个API Token，记得勾选全部权限。

4. 发布#

使用twine上传你的库到PyPi。

首先安装twine。

pip install twine

然后使用twine上传你的库。执行之后会让你输入你的API Token，复制进去即可，它不会显示出来。无需多次Ctrl V。

python -m twine upload dist/*

注意 : 如果显示你不是这个包的主人，或者显示你没有权限，或者报错403有关的错误，请更换你的库名，PyPi的库名要求全球唯一，所以重复了的话会直接上传失败。

5. 完成#

如果一切顺利，你的库就发布成功了。

可能的发布成功的输出结果:

6. 测试#

发布成功后，你可以使用pip安装你的库。

pip install <your-package-name>

7. 更新#

删除目录下的dist和.egg-info文件夹，然后重新执行build和twine即可。

记得修改版本号。

8. 一些吐槽#

这个更新必须每一次都版本不一样，不然会显示报名重复等报错，真是鸡肋。

就比如我要修改一下README.md文件，没有修改VERSION，就会在上传的时候报错说这个库已存在。😅