如何编写和发布 Python 包

Itmastergo

于 2024-08-05 16:13:17 发布

阅读量1k

点赞数 25

文章标签： python 开发语言

本文链接：https://blog.csdn.net/Itmastergo/article/details/140923317

版权

编写和发布Python包是软件开发中非常常见的一项任务。通过创建Python包，开发者可以更好地组织代码，促进代码复用，并且便于共享和分发自己的代码库。

一、准备工作

在开始编写Python包之前，确保你已经安装了以下工具：

Python：建议使用Python 3.6以上版本。
pip：Python的包管理工具。
setuptools：用于打包Python项目的工具。
twine：用于将包上传到PyPI（Python Package Index）。

可以使用以下命令来安装所需工具：

pip install setuptools twine

二、编写Python包

1. 创建项目结构

首先，创建一个项目目录，并在该目录下创建必要的文件和文件夹。假设我们的包名为mypackage，项目结构如下：

mypackage/
│
├── mypackage/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
│
├── tests/
│   ├── __init__.py
│   └── test_module1.py
│
├── setup.py
├── README.md
└── LICENSE

2. 编写包代码

在mypackage文件夹中创建两个模块文件module1.py和module2.py。这些模块中可以包含你希望打包和发布的代码。例如：

module1.py：

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

module2.py：

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero!")
    return a / b

在mypackage/__init__.py中导入这些模块：

from .module1 import add, subtract
from .module2 import multiply, divide

3. 编写测试代码

在tests文件夹中编写测试代码。确保你的代码功能正常。在这里我们使用unittest库进行测试。

test_module1.py：

import unittest
from mypackage import add, subtract

class TestModule1(unittest.TestCase):

    def test_add(self):
        self.assertEqual(add(3, 4), 7)

    def test_subtract(self):
        self.assertEqual(subtract(10, 4), 6)

if __name__ == '__main__':
    unittest.main()

4. 编写`setup.py`

setup.py是包的配置文件，用于定义包的信息和依赖项。内容如下：

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="0.1.0",
    description="A simple example Python package",
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    author="Your Name",
    author_email="your.email@example.com",
    url="https://github.com/yourusername/mypackage",
    packages=find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

5. 编写`README.md`

README.md文件包含包的介绍、安装方法和使用示例。

# mypackage

A simple example Python package.

## Installation

```sh
pip install mypackage

Usage

from mypackage import add, subtract, multiply, divide

print(add(3, 4))  # Output: 7
print(subtract(10, 4))  # Output: 6
print(multiply(3, 4))  # Output: 12
print(divide(10, 2))  # Output: 5.0

三、构建和发布包

1. 构建包

使用`setuptools`和`twine`构建包。在项目根目录运行以下命令：

python setup.py sdist bdist_wheel

这将创建两个文件夹dist和build，其中dist文件夹中包含了构建好的包文件。

2. 发布包

发布包之前，需要在PyPI注册一个账户，然后创建一个API token以便安全地上传包。

2.1 注册PyPI账户

访问PyPI官网，注册一个新账户。

2.2 创建API token

登录后，进入你的账户设置页面，创建一个新的API token。确保将其保存到安全的地方。

2.3 上传包

使用twine将包上传到PyPI。在项目根目录运行以下命令：

twine upload dist/*

系统会提示你输入PyPI账户的用户名和密码或API token。使用API token进行认证：

twine upload -u __token__ -p <your-api-token> dist/*

如果一切顺利，你的包就会成功上传到PyPI，并可以通过pip进行安装了。

四、使用和维护包

1. 安装和使用包

一旦包上传到PyPI，你就可以在任何地方通过pip安装并使用它：

pip install mypackage

然后在你的Python代码中导入并使用：

from mypackage import add, subtract, multiply, divide

print(add(3, 4))
print(subtract(10, 4))
print(multiply(3, 4))
print(divide(10, 2))

2. 维护和更新包

随着时间的推移，你可能需要对包进行更新和维护。更新包的过程与初次发布包的步骤相同，只需修改包的版本号，并确保所有修改都经过测试。

2.1 更新版本号

在setup.py中更新版本号，例如：

version="0.2.0",

2.2 构建和上传新版本

运行以下命令构建并上传新版本：

python setup.py sdist bdist_wheel
twine upload dist/*

3. 提供文档

为了方便用户使用你的包，提供详细的文档是非常重要的。你可以使用工具如Sphinx来生成文档，并将其托管在Read the Docs等平台上。

五、示例项目

这里提供一个完整的示例项目，供参考：

项目结构

example_package/
│
├── example_package/
│   ├── __init__.py
│   ├── arithmetic.py
│
├── tests/
│   ├── __init__.py
│   └── test_arithmetic.py
│
├── setup.py
├── README.md
└── LICENSE

包代码

example_package/arithmetic.py：

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero!")
    return a / b

example_package/init.py：

from .arithmetic import add, subtract, multiply, divide

测试代码

tests/test_arithmetic.py：

import unittest
from example_package import add, subtract, multiply, divide

class TestArithmetic(unittest.TestCase):

    def test_add(self):
        self.assertEqual(add(3, 4), 7)

    def test_subtract(self):
        self.assertEqual(subtract(10, 4), 6)

    def test_multiply(self):
        self.assertEqual(multiply(3, 4), 12)

    def test_divide(self):
        self.assertEqual(divide(10, 2), 5.0)

        with self.assertRaises(ValueError):
            divide(10, 0)

if __name__ == '__main__':
    unittest.main()

setup.py

from setuptools import setup, find_packages

setup(
    name="example_package",
    version="0.1.0",
    description="A simple example Python package",
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    author="Your Name",
    author_email="your.email@example.com",
    url="https://github.com/yourusername/example_package",
    packages=find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

README.md

# example_package

A simple example Python package.

## Installation

```sh
pip install example_package

Usage

from example_package import add, subtract, multiply, divide

print(add(3, 4))  # Output: 7
print(subtract(10, 4))  # Output: 6
print(multiply(3, 4))  # Output: 12
print(divide(10, 2))  # Output: 5.0

构建和上传包

python setup.py sdist bdist_wheel
twine upload dist/*

通过以上步骤，我们已经成功创建、测试、打包并发布了一个Python包。此过程不仅可以帮助你更好地组织和管理代码，也为其他开发者提供了方便使用的工具。