# 创建您自己的 Python 包
Python 是一种动态高级语言，它的简介、易读性和可扩展性使其成为数据科学家和机器学习工程师的首选。在使用 Python 时，我们经常需要使用大量的功能函数和脚本来完成特定的任务。为了更好地组织这些代码和功能，Python 支持将代码打包到 Python 包中。Python 包可以包含多个模块，这些模块是 Python 代码的集合，可以独立使用或作为 Python 应用程序的一部分。
在这篇文章中，我们将介绍如何创建您自己的 Python 包，了解 Python 包的结构、功能和创建步骤。
## 1. 准备工作
在开始创建 Python 包之前，请确保您已经安装了 Python。在开始创建 Python 包时，我们需要了解以下 Python 包所需的基本组件：
- 包目录结构及其文件作用
- 包元数据文件（setup.py）
- 使用的代码和依赖项
理解这些组件后，让我们开始创建 Python 包！
## 2. 包目录结构
创建 Python 包时，我们需要定义包目录结构。下面是一个通用的 Python 包的目录结构：
```
my_package/
├── my_package/
│ ├── __init__.py
│ ├── module_1.py
│ └── module_2.py
└── setup.py
```
该目录结构主要由两个目录组成：
- 包目录：该目录包含了您要组织到 Python 模块中的文件。这里，我们可以定义多个模块和子包。
- 元数据文件：包含有关包的元数据信息的文件，例如名称、版本、作者等。元数据文件使我们能够轻松地为我们的模块添加功能，例如依赖项管理和安装。
下面，我们将会详细介绍这两个目录的内容和作用。
### 2.1 包目录
包目录包含了用于组织 Python 模块的文件和子包。下面是一个包含两个模块的示例：
```
my_package/
└── my_package/
├── __init__.py
├── module_1.py
└── module_2.py
```
其中，__init__.py 是 Python 中的特殊文件，它指示 Python 解释器该目录应视为包。该文件通常是空文件，但也可以包含有关包的调用、导入和其他元数据信息。
其他文件（例如 module_1.py 和 module_2.py）是包中实际代码的文件。在一个典型的包中，我们可能有多个这样的模块，每个模块负责提供特定的功能或任务。
### 2.2 元数据文件
元数据文件是包含包信息和元数据的特殊 Python 文件。在 Python 中，我们使用 setup.py 文件来指定有关我们创建包的信息，例如名称、版本、描述等。我们还可以在元数据中指定其他用于打包、安装和分发包的信息。
在我们的示例中，setup.py 包含以下内容：
```
from setuptools import setup
setup(name='my_package',
version='0.1',
description='A sample Python package',
url='https://github.com/username/my_package',
author='Your Name',
author_email='your_email@example.com',
license='MIT',
packages=['my_package'],
install_requires=[
'numpy',
'pandas',
'matplotlib'
],
zip_safe=False)
```
setup.py 声明的各项信息包括：
- **name**：包的名称。
- **version**：包的版本。
- **description**：用一句话描述包的内容。
- **url**：包的托管源。
- **author**：包的作者。
- **author_email**：作者的联系邮箱。
- **license**：包的许可证。
- **packages**：包含模块的列表。
- **install_requires**：该项目依赖的包。
- **zip_safe**：是否可以作为 "zipfile" 安装和分发。
## 3. 创建 Python 包
现在，我们已经准备好创建 Python 包了！我们需要完成以下步骤：
1. 创建包的目录结构。
2. 填写包的元数据文件。
3. 编写我们的代码并将其组织在包的 Python 模块中。
让我们来完成这些步骤。
### 3.1 创建包目录结构
首先，我们需要创建包的目录结构。我们可以在任何位置创建包的目录结构，例如在桌面或 ~/Documents/ 中。下面，我们在我的文档目录下创建一个名为 my_package 的目录，在其中创建初始的 __init__.py 文件和 Python 模块文件：
```
mkdir ~/Documents/my_package
touch ~/Documents/my_package/__init__.py
touch ~/Documents/my_package/module_1.py
touch ~/Documents/my_package/module_2.py
```
### 3.2 填写元数据文件
接下来，我们需要填写元数据文件 setup.py。在此文件中，我们将列出有关包的所有详细信息。这里是一个快速的示例：
from setuptools import setup
setup(name='my_package',
version='0.1',
description='A sample Python package',
url='https://github.com/username/my_package',
author='Your Name',
author_email='your_email@example.com',
license='MIT',
packages=['my_package'],
install_requires=[
'numpy',
'pandas',
'matplotlib'
],
zip_safe=False)
在此示例中，我们使用 setuptools 库来构建包。除了列出名称、版本和依赖项之外，我们还指定包含模块的目录 'my_package'，以及包的许可证。
### 3.3 编写包的 Python 模块代码
我们已经定义了包的目录结构和元数据，现在是时候编写我们的代码了。在我们的示例中，我们将编写两个模块，一个用于生成数据，一个用于显示数据。我们将分别编写这两个模块中的代码。
#### 3.3.1 数据模块
我们的数据模块将会生成一个简单的数据集，该数据集由三个变量组成：
import numpy as np
import pandas as pd
def generate_data(n_samples):
"""生成一个包含三个变量的简单数据集。
参数：
n_samples -- 数据集中的样本数。
返回：
一个 Pandas DataFrame，它包含三列变量。
"""
x = np.linspace(-1, 1, n_samples)
y = x ** 2
z = 'up' if np.random.random() < 0.5 else 'down'
data = pd.DataFrame({
'x': x,
'y': y,
'z': z
})
return data
在此模块中，我们从 numpy 导入 NumPy 库以生成简单的数据，并从 pandas 导入 pandas 库以将数据存储在 DataFrame 中。我们的 generate_data 函数将接收一个 n_samples 参数，该参数指定我们要生成的数据点数。我们将使用该参数来创建一条由 x 变量、y 变量和 z 变量组成的线。其中，z 为二分类变量，其类别为上涨（up）和下跌（down）之一。
该函数将生成一个 Pandas DataFrame 对象，由于返回的 DataFrame 包含变量 x、y 和 z，因此将该数据集命名为 'xyz'。
#### 3.3.2 显示模块
我们的第二个模块将包含代码，用于显示我们的数据集，并在任何要使用时提供方便的函数。该代码将使用 matplotlib 库来生成图表。下面是我们的显示模块代码:
import matplotlib.pyplot as plt
def plot_data(data, marker='o'):
"""绘制数据集的散点图。
参数：
data -- 要绘制的数据集。
marker -- 数据点的标记字符，默认为 "o"。
"""
plt.scatter(data['x'], data['y'], c=data['z'], marker=marker)
plt.xlabel('x')
plt.ylabel('y')
plt.title('My Data')
plt.show()
在此模块中，我们从 matplotlib 导入 pyplot 库。我们定义了一个名为 plot_data 的函数，该函数将接受我们的数据集和一个 marker 参数。该函数将使用 plt.scatter 函数绘制我们的数据集，并指定标记字符为所提供的 marker 参数。函数还将定义 x 轴和 y 轴的标签，设置标题，然后显示图表。
## 4. 使用您的 Python 包
现在，我们已经创建了我们的 Python 包，在我们的 my_package 目录下，我们可以创建三个文件 __init__.py、module_1.py 和 module_2.py，其中包含我们的 Python 代码。
为了安装我们的 Python 包，打开终端，在包的顶级目录下执行以下命令：
```
pip install .
```
这将会安装我们的 Python 包。
接下来，我们来测试一下刚刚创建的 Python 包。我们先打开 Python 交互式环境，导入模块，并用 generate_data 来生成我们的数据集，然后用 plot_data 将其绘制出来：
>>> from my_package import module_1, module_2
>>> data = module_1.generate_data(n_samples=50)
>>> module_2.plot_data(data)
下面是我们的 Python 包生成的图表示例：
如您所见，我们创建的 Python 包提供了方便而强大的方式来组织、存储和共享我们的 Python 代码。通过将代码打包为 Python 包，我们可以轻松地在不同的项目和组织中重复使用我们的代码，并通过简单的 pip 安装来与其他人分享这些代码。
## 5. 总结
在这篇文章中，我们学习了如何创建一个 Python 包。我们了解了包的目录结构和元数据文件，并编写了两个 Python 模块，一个用于生成数据，另一个用于显示数据。
要使用我们的 Python 包，我们只需打包目录结构和元数据文件，然后使用 pip 安装即可。我们还演示了如何在 Python 中使用导入的模块来生成和显示我们的数据集。