Python 导包、分包完全教程

第一部分：Python导包基础（完全新手友好）

第一章：理解Python中的"包"和"模块"

1.1 什么是模块？

PYTHON 复制代码

# 一个.py文件就是一个模块
# example.py 就是一个名为example的模块
def say_hello():
    print("你好！")


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

1.2 什么是包？

TEXT 复制代码

# 包是一个包含__init__.py文件的文件夹
my_package/
    __init__.py    # 这个文件让Python知道这是包
    module1.py
    module2.py

第二章：最简单的导包方式

2.1 同一个文件夹内的导入

TEXT 复制代码

项目结构：
project/
    main.py
    utils.py

PYTHON 复制代码

# utils.py
def greet(name):
    return f"你好，{name}！"


def calculate_sum(numbers):
    return sum(numbers)

PYTHON 复制代码

# main.py - 方法1：导入整个模块
import utils

result = utils.greet("小明")
print(result)  # 输出：你好，小明！

total = utils.calculate_sum([1, 2, 3, 4, 5])
print(total)   # 输出：15

PYTHON 复制代码

# main.py - 方法2：导入特定功能
from utils import greet, calculate_sum

result = greet("小红")  # 直接使用，不用加 utils.
print(result)

PYTHON 复制代码

# main.py - 方法3：导入并重命名
from utils import greet as say_hello

say_hello("小张")  # 使用新名字

2.2 导入外部库

PYTHON 复制代码

# Python内置库
import math
import random
import datetime

# 第三方库（需要先安装）
# pip install requests
import requests

第三章：理解绝对导入和相对导入

3.1 创建多级目录结构

TEXT 复制代码

my_project/
│   main.py
│
├───database/
│   │   __init__.py
│   │   connector.py
│   │   models.py
│
└───utils/
    │   __init__.py
    │   math_tools.py
    │   string_tools.py

3.2 绝对导入（推荐新手使用）

PYTHON 复制代码

# main.py
from database.connector import connect_db
from utils.math_tools import add_numbers
from utils.string_tools import format_text

3.3 相对导入（在包内部使用） 若直接运行的是models.py

PYTHON 复制代码

# 在 database/models.py 中
from .connector import connect_db    # . 表示同一目录
from ..utils.math_tools import add_numbers  # .. 表示上级目录

若直接运行的是main.py

PYTHON 复制代码

# 在 database/models.py 中
from database.connector import connect_db    # 与main同一目录
from utils.math_tools import add_numbers  # 与main同一目录

第四章：init.py 文件的妙用

4.1 最简单的 init.py

PYTHON 复制代码

# database/__init__.py
# 空文件也可以，但有它才算是包

4.2 有组织的 init.py

PYTHON 复制代码

# utils/__init__.py
# 集中导入，方便外部使用
from .math_tools import *
from .string_tools import *


# 或者更精确的控制
__all__ = ['add_numbers', 'multiply_numbers', 'format_text']

PYTHON 复制代码

# 这样在外面就可以
from utils import add_numbers  # 不需要知道math_tools的存在

4.3 包级别的变量和初始化

PYTHON 复制代码

# utils/__init__.py
# 包版本信息
__version__ = "1.0.0"
__author__ = "你的名字"


# 包初始化代码
print("正在加载工具包...")


# 包级别的配置
DEFAULT_CONFIG = {
    "log_level": "INFO",
    "timeout": 30
}

第二部分：项目分包实践（结构化思维）

第五章：从小项目到中大型项目的演变

5.1 初级阶段：扁平结构

TEXT 复制代码

simple_app/
    app.py          # 主程序
    config.py       # 配置
    helpers.py      # 辅助函数
    data.json       # 数据文件

5.2 中级阶段：按功能分包

TEXT 复制代码

medium_app/
│   main.py                    # 程序入口
│   requirements.txt           # 依赖列表
│   README.md                 # 说明文档
│
├───core/                     # 核心业务逻辑
│   │   __init__.py
│   │   calculator.py        # 计算器类
│   │   validator.py         # 验证器
│
├───ui/                       # 用户界面
│   │   __init__.py
│   │   window.py           # 主窗口
│   │   widgets.py          # 小部件
│
├───data/                     # 数据处理
│   │   __init__.py
│   │   loader.py           # 数据加载
│   │   saver.py            # 数据保存
│
└───utils/                   # 通用工具
    │   __init__.py
    │   logger.py           # 日志工具
    │   formatter.py        # 格式化工具

5.3 专业阶段：标准Python项目结构

TEXT 复制代码

professional_app/
│
├───src/                     # 源代码目录（推荐结构）
│   └───my_app/              # 你的包名
│       │   __init__.py
│       │   __main__.py     # 命令行入口：python -m my_app
│       │   cli.py          # CLI接口
│       │   config.py       # 配置管理
│       │
│       ├───core/
│       │   │   __init__.py
│       │   │   business_logic.py
│       │   │   models.py
│       │
│       ├───api/
│       │   │   __init__.py
│       │   │   routes.py
│       │   │   handlers.py
│       │
│       └───utils/
│           │   __init__.py
│           │   helpers.py
│           │   decorators.py
│
├───tests/                   # 测试目录
│   │   __init__.py
│   │   test_core.py
│   │   test_utils.py
│   │   conftest.py         # pytest配置
│
├───docs/                    # 文档
│       index.md
│       tutorial.md
│
├───examples/               # 示例代码
│       basic_usage.py
│       advanced_features.py
│
├───scripts/                # 脚本
│       setup_env.py
│       generate_data.py
│
│   .gitignore              # Git忽略文件
│   pyproject.toml          # 项目配置（现代方式）
│   setup.py               # 安装配置（传统方式）
│   README.md              # 项目说明
│   LICENSE               # 许可证
└───requirements.txt       # 依赖包列表

最佳实践指南

使用src布局：将源代码放在src目录下
清晰的分层：按功能而不是按类型组织
最小化import：只导入需要的模块
使用__init__.py控制导出：明确公开的API