核心概念：什么是 Python 包？
一个 Python 包本质上就是一个包含 __init__.py 文件的目录，这个 __init__.py 文件向 Python 表明,这个目录应该被当作一个包来处理。
- 简单包：一个目录 + 一个
__init__.py文件。 - 包内可以有多个模块：你可以在这个目录里放置多个
.py文件（模块），以及子包（即包含__init__.py的子目录）。
第一步：创建基本的包结构
假设我们有一个简单的 calculator.py 文件，我们想把它变成一个名为 my_calculator 的包。
原始文件结构：
my_project/
└── calculator.pycalculator.py 的内容：
# calculator.py
def add(a, b):
"""返回两个数的和"""
return a + b
def subtract(a, b):
"""返回两个数的差"""
return a - b
目标： 我们想通过 my_calculator.add() 来调用这个函数。
操作步骤：
-
创建一个目录：将
calculator.py移动到一个新的目录中，这个目录的名字就是你的包名，my_calculator。 -
创建
__init__.py文件：在my_calculator目录中，创建一个名为__init__.py的空文件，这个文件是包的“身份证”,必不可少。
现在你的项目结构看起来像这样：
my_project/
└── my_calculator/
├── __init__.py
└── calculator.py__init__.py 的作用：
- 标识目录为包：这是最基本的作用。
- 控制包的导入行为：你可以在
__init__.py中编写代码，来决定当用户import my_calculator时,会得到什么。
第二步：让包更易用（推荐做法）
如果我们想使用这个包,我们需要这样做：
import my_calculator.calculator result = my_calculator.calculator.add(5, 3) print(result) # 输出: 8
这有点冗长，我们可以通过修改 __init__.py 来让它更简洁。
修改 my_calculator/__init__.py 文件：
# my_calculator/__init__.py from .calculator import add, subtract # 这里的 "." 表示从当前包（my_calculator）中导入
当你导入 my_calculator 时，它会自动将 add 和 sub 函数加载进来。
测试一下：
在你的项目根目录（my_project）下创建一个 main.py 文件来测试：
# main.py
import my_calculator
# 现在可以直接使用 my_calculator.add() 了
result_add = my_calculator.add(10, 2)
print(f"10 + 2 = {result_add}")
result_sub = my_calculator.subtract(10, 2)
print(f"10 - 2 = {result_sub}")
运行 python main.py,你会得到预期的输出。
第三步：进阶实践
一个完整的、可供他人安装的包,通常还需要以下文件：
包含多个模块
一个包通常由多个功能模块组成，我们可以将 calculator.py 拆分成 arithmetic.py（算术）和 geometry.py（几何）。
新的结构：
my_project/
└── my_calculator/
├── __init__.py
├── arithmetic.py # 算术模块
└── geometry.py # 几何模块arithmetic.py
# my_calculator/arithmetic.py
def add(a, b):
return a + b
def subtract(a, b):
return a - b
geometry.py
# my_calculator/geometry.py
def area_of_circle(radius):
import math
return math.pi * radius ** 2
更新 __init__.py 以导入所有模块的公共接口：
# my_calculator/__init__.py from .arithmetic import add, subtract from .geometry import area_of_circle
测试：
# main.py import my_calculator print(my_calculator.add(5, 3)) print(my_calculator.area_of_circle(10))
添加 setup.py 文件（用于安装你的包）
如果你想将这个包安装到你的 Python 环境中，或者上传到 PyPI，你需要一个 setup.py 文件。
在项目根目录 my_project 下创建 setup.py：
# setup.py
from setuptools import setup, find_packages
setup(
name="my-calculator", # 包在 PyPI 上的名称
version="0.1.0", # 版本号
author="Your Name", # 作者
author_email="your.email@example.com", # 作者邮箱
description="A simple calculator package", # 简短描述
long_description=open("README.md").read(), # 详细描述（通常来自 README.md）
long_description_content_type="text/markdown",
url="https://github.com/yourusername/my-calculator", # 项目主页
packages=find_packages(), # 自动查找所有包
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.6', # 最低支持的 Python 版本
)
如何使用 setup.py 安装：
- 确保你已安装
setuptools：pip install setuptools - 在
my_project目录下，打开终端，运行：pip install -e .
-e或--editable表示“可编辑安装”，这意味着你对包源代码的修改会立即生效，无需重新安装,这对于开发非常方便。
安装完成后，你可以在任何地方（只要 Python 环境已激活）直接 import my_calculator,而无需关心它在哪里。
添加 README.md 和 LICENSE
README.md：向其他用户介绍你的包,说明如何安装和使用。LICENSE：声明你的包的许可证（MIT, Apache 2.0）,这是开源项目的重要组成部分。
第四步：使用 pyproject.toml（现代标准）
从 Python 3.11 开始，pyproject.toml 是构建和分发包的推荐标准，取代了旧的 setup.py + setup.cfg 方式，它更清晰，是 PEP 517 和 PEP 518 的核心。
创建 pyproject.toml 文件（在项目根目录 my_project 下）：
# pyproject.toml
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "my-calculator"
version = "0.1.0"
authors = [
{ name="Your Name", email="your.email@example.com" },
]
description = "A simple calculator package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
Homepage = "https://github.com/yourusername/my-calculator"
Issues = "https://github.com/yourusername/my-calculator/issues"
如何使用 pyproject.toml 安装：
安装方式完全相同，pip 会自动识别 pyproject.toml 文件。
pip install -e .
注意： 如果使用 pyproject.toml，通常不再需要 setup.py 文件,除非有非常特殊的构建需求。
从文件到包的完整步骤
- 创建目录：将你的
.py文件放入一个以其功能命名的目录中（my_utils）。 - 添加
__init__.py：在目录中创建一个空的__init__.py文件，将其标记为 Python 包。 - 重构导入：在
__init__.py中使用from .module import function的语法，将包内模块的函数/类暴露出来,简化用户的调用方式。 - 组织代码：随着功能增多，在包内创建多个
.py模块来组织代码。 - 添加元数据：创建
setup.py或pyproject.toml文件，定义包的名称、版本、作者等信息,以便安装和分发。 - 编写文档：创建
README.md说明如何使用你的包，LICENSE文件声明其开源许可。 - 安装测试：使用
pip install -e .进行可编辑安装，并在项目中测试import你的包是否成功。
遵循这些步骤，你就可以将一个简单的 Python 文件，发展成一个结构良好、易于维护和分发的专业 Python 包了。
