python如何使用自己的包

Python 使用自己的包主要有以下步骤：创建包结构、编写代码、安装包、导入并使用包、配置文件、打包上传。 其中，安装包是一个关键步骤，它可以通过 pip 工具方便地进行。具体步骤如下：

安装自己的包

创建包结构

首先，创建一个包含包的目录结构。通常情况下，一个包包含一个或多个模块（.py 文件），以及一个特殊的 __init__.py 文件。__init__.py 文件的存在表明该目录是一个包。

例如，创建一个名为 mypackage 的包，其目录结构如下：

mypackage/ __init__.py module1.py module2.py subpackage/ __init__.py module3.py

编写代码

在包的目录结构中编写代码。例如，在 module1.py 中编写如下代码：

# mypackage/module1.py
def hello():
    print("Hello from module1")

安装包

接下来，创建一个 setup.py 文件，这是一个安装脚本，用于告诉 setuptools 如何打包和安装你的包。例子如下：

# setup.py
from setuptools import setup, find_packages
setup(
    name='mypackage',
    version='0.1',
    packages=find_packages(),
    install_requires=[
        # 在此处列出所有包的依赖项
    ],
)

然后，运行以下命令来安装包：

pip install .

这将使用 setup.py 文件中的信息来安装包。

导入并使用包

安装完成后，就可以在 Python 代码中导入并使用包了。例如：

# 使用包
from mypackage.module1 import hello
hello()

配置文件和打包上传

配置文件

除了 setup.py 文件，有时还需要创建其他配置文件，例如 MANIFEST.in、setup.cfg 等，用于更详细地配置包的安装和分发。例如，MANIFEST.in 文件可以指定要包含在分发包中的额外文件：

# MANIFEST.in include README.md

打包和上传

为了将包上传到 Python 包索引（PyPI），需要先打包。可以使用 setuptools 提供的 bdist 和 sdist 命令来打包：

python setup.py sdist bdist_wheel

然后，使用 twine 工具将包上传到 PyPI：

twine upload dist/*

一、创建包结构

1.1、创建目录结构

创建包的第一步是创建目录结构。包的目录结构通常包括一个或多个模块（.py 文件），以及一个特殊的 __init__.py 文件。__init__.py 文件的存在表明该目录是一个包。目录结构可以通过命令行或文件管理器来创建。

例如，创建一个名为 mypackage 的包，其目录结构如下：

mypackage/ __init__.py module1.py module2.py subpackage/ __init__.py module3.py

1.2、编写模块代码

在包的目录结构中编写代码。例如，在 module1.py 中编写如下代码：

# mypackage/module1.py
def hello():
    print("Hello from module1")

在 module2.py 中编写如下代码：

# mypackage/module2.py
def greet(name):
    print(f"Hello, {name}")

在 subpackage/module3.py 中编写如下代码：

# mypackage/subpackage/module3.py
def farewell(name):
    print(f"Goodbye, {name}")

二、安装包

2.1、创建 setup.py 文件

接下来，创建一个 setup.py 文件，这是一个安装脚本，用于告诉 setuptools 如何打包和安装你的包。setup.py 文件的基本结构如下：

# setup.py
from setuptools import setup, find_packages
setup(
    name='mypackage',
    version='0.1',
    packages=find_packages(),
    install_requires=[
        # 在此处列出所有包的依赖项
    ],
)

2.2、运行安装命令

在命令行中导航到包含 setup.py 文件的目录，然后运行以下命令来安装包：

pip install .

这将使用 setup.py 文件中的信息来安装包。

三、导入并使用包

3.1、导入包

安装完成后，就可以在 Python 代码中导入并使用包了。例如：

# 使用包
from mypackage.module1 import hello
from mypackage.module2 import greet
from mypackage.subpackage.module3 import farewell
hello()
greet("Alice")
farewell("Bob")

3.2、测试包

为了确保包的功能正常，可以编写测试代码。例如，创建一个 test.py 文件，内容如下：

# test.py
from mypackage.module1 import hello
from mypackage.module2 import greet
from mypackage.subpackage.module3 import farewell
def test_package():
    hello()
    greet("Alice")
    farewell("Bob")
if __name__ == "__main__":
    test_package()

运行 test.py 文件，确保所有功能正常：

python test.py

四、配置文件

4.1、MANIFEST.in 文件

除了 setup.py 文件，有时还需要创建其他配置文件，例如 MANIFEST.in 文件。MANIFEST.in 文件可以指定要包含在分发包中的额外文件。示例如下：

# MANIFEST.in include README.md include LICENSE recursive-include mypackage/data *

4.2、setup.cfg 文件

setup.cfg 文件是一个可选的配置文件，用于进一步配置包的安装和分发。示例如下：

# setup.cfg
[metadata]
description-file = README.md

五、打包和上传

5.1、打包

为了将包上传到 Python 包索引（PyPI），需要先打包。可以使用 setuptools 提供的 bdist 和 sdist 命令来打包：

python setup.py sdist bdist_wheel

这将生成分发包文件，通常位于 dist 目录中。

5.2、上传

使用 twine 工具将包上传到 PyPI：

twine upload dist/*

上传成功后，包将出现在 PyPI 上，其他用户可以通过 pip install 命令来安装该包。

六、包的版本管理和依赖管理

6.1、版本管理

在开发过程中，可能需要发布多个版本的包。可以通过在 setup.py 文件中设置 version 参数来管理版本。例如：

# setup.py
setup(
    name='mypackage',
    version='0.2',
    packages=find_packages(),
    install_requires=[
        # 在此处列出所有包的依赖项
    ],
)

6.2、依赖管理

在 setup.py 文件中，可以通过 install_requires 参数来指定包的依赖项。例如：

# setup.py
setup(
    name='mypackage',
    version='0.1',
    packages=find_packages(),
    install_requires=[
        'requests>=2.20.0',
        'numpy>=1.18.0',
    ],
)

这将确保在安装 mypackage 时，自动安装所需的依赖项。

七、包的文档编写

7.1、文档结构

为包编写文档是一个重要的步骤，可以帮助用户理解和使用包的功能。通常，文档包括以下内容：

README.md：包的简介、安装说明、使用示例等。
CHANGELOG.md：包的版本历史和更新日志。
docs/：详细的文档，通常使用 Sphinx 等工具生成。

7.2、使用 Sphinx 生成文档

Sphinx 是一个用于生成 Python 文档的工具。可以通过以下步骤使用 Sphinx 生成文档：

安装 Sphinx：

pip install sphinx

初始化 Sphinx 项目：

sphinx-quickstart docs

配置 conf.py 文件，添加包的路径：

# docs/conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

编写文档源文件，例如 index.rst：

# docs/index.rst
Welcome to mypackage's documentation!
=====================================
.. toctree::
   :maxdepth: 2
   :caption: Contents:
   module1
   module2
   subpackage/module3

生成 HTML 文档：

sphinx-build -b html docs docs/_build

生成的 HTML 文档位于 docs/_build 目录中，可以使用浏览器查看。

八、包的测试

8.1、编写测试代码

为了确保包的功能正常，需要编写测试代码。通常，测试代码放在一个单独的目录中，例如 tests/。测试代码可以使用 Python 的内置 unittest 模块或第三方测试框架如 pytest。

示例测试代码：

# tests/test_module1.py
import unittest
from mypackage.module1 import hello
class TestModule1(unittest.TestCase):
    def test_hello(self):
        self.assertEqual(hello(), "Hello from module1")
if __name__ == '__main__':
    unittest.main()

8.2、运行测试

可以使用 unittest 或 pytest 运行测试代码。例如，使用 unittest：

python -m unittest discover tests

使用 pytest：

pytest tests

确保所有测试通过后，才发布包。

九、CI/CD 集成

9.1、使用 GitHub Actions

CI/CD（持续集成和持续交付）可以自动化测试和部署过程。GitHub Actions 是一个流行的 CI/CD 工具，可以用于自动化包的测试和发布。

示例 GitHub Actions 配置文件 .github/workflows/python-package.yml：

name: Python package on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install . pip install pytest - name: Test with pytest run: | pytest

9.2、发布到 PyPI

可以通过 GitHub Actions 自动将包发布到 PyPI。需要在 GitHub 仓库中配置 PyPI API 令牌，然后在 GitHub Actions 配置文件中添加发布步骤：

name: Publish Python package on: release: types: [created] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/*

这样，每当在 GitHub 仓库中创建新版本时，GitHub Actions 将自动构建并发布包到 PyPI。

十、示例包

10.1、创建示例包

为了更好地理解上述步骤，可以创建一个示例包。以下是一个示例包的目录结构和代码：

example_package/ __init__.py math_operations.py string_operations.py sub_package/ __init__.py list_operations.py setup.py README.md tests/ test_math_operations.py test_string_operations.py test_list_operations.py .github/ workflows/ python-package.yml

10.2、示例代码

example_package/math_operations.py：

# example_package/math_operations.py
def add(a, b):
    return a + b
def subtract(a, b):
    return a - b

example_package/string_operations.py：

# example_package/string_operations.py
def to_upper(s):
    return s.upper()
def to_lower(s):
    return s.lower()

example_package/sub_package/list_operations.py：

# example_package/sub_package/list_operations.py
def append_element(lst, element):
    lst.append(element)
    return lst
def remove_element(lst, element):
    lst.remove(element)
    return lst

setup.py：

# setup.py
from setuptools import setup, find_packages
setup(
    name='example_package',
    version='0.1',
    packages=find_packages(),
    install_requires=[],
)

README.md：

# Example Package This is an example Python package. ## Installation ```sh pip install .

Usage

from example_package.math_operations import add
print(add(1, 2))
from example_package.string_operations import to_upper
print(to_upper("hello"))
from example_package.sub_package.list_operations import append_element
print(append_element([1, 2, 3], 4))


`tests/test_math_operations.py`：
```python
tests/test_math_operations.py
import unittest
from example_package.math_operations import add, subtract
class TestMathOperations(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(1, 2), 3)
    def test_subtract(self):
        self.assertEqual(subtract(2, 1), 1)
if __name__ == '__main__':
    unittest.main()

tests/test_string_operations.py：

# tests/test_string_operations.py
import unittest
from example_package.string_operations import to_upper, to_lower
class TestStringOperations(unittest.TestCase):
    def test_to_upper(self):
        self.assertEqual(to_upper("hello"), "HELLO")
    def test_to_lower(self):
        self.assertEqual(to_lower("HELLO"), "hello")
if __name__ == '__main__':
    unittest.main()

tests/test_list_operations.py：

# tests/test_list_operations.py
import unittest
from example_package.sub_package.list_operations import append_element, remove_element
class TestListOperations(unittest.TestCase):
    def test_append_element(self):
        self.assertEqual(append_element([1, 2, 3], 4), [1, 2, 3, 4])
    def test_remove_element(self):
        self.assertEqual(remove_element([1, 2, 3], 2), [1, 3])
if __name__ == '__main__':
    unittest.main()

.github/workflows/python-package.yml：

# .github/workflows/python-package.yml name: Python package on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install . pip install pytest - name: Test with pytest run: | pytest