Python 模块系统入门

# greetings.py —— 这就是一个模块，模块名为 greetings

def hello(name: str) -> str:
    """返回问候语"""                    # 定义函数
    return f"Hello, {name}"

version = "1.0"                         # 定义变量

class Greeter:                          # 定义类
    def __init__(self, lang: str):
        self.lang = lang

if __name__ == '__main__':              # 模块自测代码
    print(hello('world')

#!/usr/bin/env python3
"""演示 import 机制的内部流程"""

import sys

# ── 步骤 1：检查 sys.modules 缓存 ──────────────────────────────
# import 时 Python 首先查看 sys.modules 字典
# 如果模块已加载过，直接返回缓存对象，不会重复执行模块代码
print('math' in sys.modules)    # False（首次导入前）
import math
print('math' in sys.modules)    # True（导入后进入缓存）
print(sys.modules['math'])      # <module 'math' from ...>

# ── 步骤 2：Finder 查找模块 ────────────────────────────────────
# sys.meta_path 包含一系列 Finder 对象，依次尝试定位模块
for finder in sys.meta_path:
    print(finder)               # BuiltinFinder, FrozenFinder, PathFinder ...

# ── 步骤 3：Loader 加载并执行 ──────────────────────────────────
# Finder 找到模块后返回 ModuleSpec，Loader 据此创建模块对象并执行代码
# 执行后模块对象被缓存到 sys.modules

# ── 步骤 4：绑定模块名 ─────────────────────────────────────────
# 当前作用域中绑定模块名，指向缓存中的模块对象
print(math.pi)                  # 3.141592653589793

#!/usr/bin/env python3
"""查看当前 Python 环境的模块搜索路径"""

import sys

print("=== sys.path 搜索路径（按优先级排列）===")
for i, path in enumerate(sys.path, 1):
    print(f"  {i}. {path}")

print("\n=== 内置模块列表（部分）===")
print(list(sys.builtin_module_names)[:10], "...")

# 分析模块加载耗时（命令行方式）
# python -X importtime your_script.py
# 输出示例：
# import time:       123 |         123 | math
# import time:       456 |         579 | numpy

#!/usr/bin/env python3
"""五种 import 语法的完整对比示例"""

# ── 方式 1：import x ──────────────────────────────────────────
# 最安全的方式，命名空间完全隔离
import math                          # 导入整个 math 模块
print(math.sqrt(16))                 # 调用时必须带模块名前缀 → 4.0
print(math.pi)                       # → 3.141592653589793

# ── 方式 2：import x as y ─────────────────────────────────────
# 给模块起别名，社区有约定俗成的写法
import math as m                     # 别名 m 指向 math 模块对象
print(m.sqrt(16))                    # → 4.0
# 常见约定：import numpy as np / import pandas as pd

# ── 方式 3：from x import y ───────────────────────────────────
# 只导入需要的对象，直接使用，无需前缀
from math import sqrt, pi            # 只导入 sqrt 函数和 pi 常量
print(sqrt(16))                      # 直接调用，无需 math. 前缀 → 4.0
print(pi)                            # → 3.141592653589793

# ── 方式 4：from x import y as z ──────────────────────────────
# 导入特定对象并起别名
from math import pi as PI            # pi 在当前作用域叫 PI
print(PI)                            # → 3.141592653589793

# ── 方式 5：from x import * ──────────────────────────────────
# 导入模块所有公开名称，严重污染命名空间，不推荐
from math import *                   # math 中所有名称进入当前作用域
print(sqrt(16))                      # 能用，但不知道 sqrt 从哪来的
# 危险：可能覆盖同名的自定义函数！

#!/usr/bin/env python3
"""演示 from x import * 导致的名称覆盖问题"""

def sqrt(n):
    """自定义整数平方根"""
    return int(n ** 0.5)

print(sqrt(8))                       # → 2（使用自定义版本）

from math import *                   # math.sqrt 覆盖了自定义 sqrt
print(sqrt(8))                       # → 2.8284271247461903（被覆盖！）

# 结论：永远不要在生产代码中使用 from x import *

my_project/
├── main.py                       # 入口脚本
└── my_package/
    ├── __init__.py               # 包初始化，暴露公共 API
    ├── math_utils.py             # 数学工具模块
    └── string_utils.py           # 字符串工具模块

# my_package/__init__.py
"""my_package - 一个工具函数包"""

from .math_utils import add, subtract       # 从子模块导入，提升到包级别
from .string_utils import greet             # 同上

__version__ = "1.0.0"                       # 包级别变量

__all__ = ['add', 'subtract', 'greet']      # 控制 from my_package import * 的范围

# my_package/math_utils.py
"""数学工具函数模块"""

def add(a: float, b: float) -> float:
    """两数相加"""
    return a + b

def subtract(a: float, b: float) -> float:
    """两数相减"""
    return a - b

def _internal_helper(x: float) -> float:    # 下划线前缀表示内部函数
    """内部辅助函数，不建议外部直接调用"""
    return x * 2

# 模块内自测
if __name__ == '__main__':
    print(f"10 + 5 = {add(10, 5)}")
    print(f"10 - 5 = {subtract(10, 5)}")

# my_package/string_utils.py
"""字符串工具函数模块"""

def greet(name: str) -> str:
    """返回问候语"""
    return f"你好, {name}!"

def capitalize_words(text: str) -> str:
    """将每个单词的首字母大写"""
    return ' '.join(word.capitalize() for word in text.split()

if __name__ == '__main__':
    print(greet("张三")
    print(capitalize_words("hello world")

#!/usr/bin/env python3
"""演示包的两种导入方式"""

# 方式 1：通过包名间接使用（__init__.py 已做转发）
import my_package
print(my_package.add(5, 3))          # → 8
print(my_package.greet("Alice"))     # → 你好, Alice!
print(my_package.__version__)        # → 1.0.0

# 方式 2：直接导入子模块
from my_package.math_utils import add, subtract
print(add(10, 20))                   # → 30
print(subtract(10, 5))               # → 5

# 方式 3：利用 __init__.py 转发，直接导入包级名称
from my_package import add, greet
print(add(1, 2))                     # → 3
print(greet("Bob"))                  # → 你好, Bob!

# my_package/__init__.py

from .math_utils import add, subtract, _internal_helper
from .string_utils import greet, capitalize_words

__all__ = ['add', 'greet']           # import * 时只导入 add 和 greet

#!/usr/bin/env python3
"""演示 __all__ 的效果"""

from my_package import *

print(add(1, 2))                     # OK，add 在 __all__ 中
print(greet("Alice"))                # OK，greet 在 __all__ 中

# print(subtract(5, 3))             # NameError! subtract 不在 __all__ 中
# print(capitalize_words("hi"))     # NameError! capitalize_words 不在 __all__ 中

from . import module_a              # 导入同目录下的 module_a（当前包）
from .module_a import func_a        # 从同目录 module_a 导入 func_a
from .. import module_b             # 导入上级目录的 module_b（父包）
from ..subpackage import module_c   # 从父包的 subpackage 子包导入 module_c
from ... import top_level           # 上上级（不推荐超过两级）

my_app/
├── main.py
└── services/
    ├── __init__.py
    ├── auth.py
    └── database/
        ├── __init__.py
        └── queries.py

# services/database/queries.py

# 绝对导入：从项目根目录写完整路径
from services.auth import validate_token       # 清晰但包重命名要改

# 相对导入：从当前位置出发
from ..auth import validate_token              # 包重命名不影响
from . import queries                          # 当前包内的模块

#!/usr/bin/env python3
# calculator.py
"""计算器模块 - 演示 __name__ 的最佳实践"""


def add(a: float, b: float) -> float:
    """加法"""
    return a + b


def subtract(a: float, b: float) -> float:
    """减法"""
    return a - b


def main():
    """主函数：处理命令行交互"""
    import argparse                                    # 延迟导入，仅命令行使用
    
    parser = argparse.ArgumentParser(description="简易计算器")
    parser.add_argument("a", type=float, help="第一个数")
    parser.add_argument("op", choices=["+", "-"], help="运算符")
    parser.add_argument("b", type=float, help="第二个数")
    args = parser.parse_args()
    
    if args.op == "+":
        print(f"{args.a} + {args.b} = {add(args.a, args.b)}")
    elif args.op == "-":
        print(f"{args.a} - {args.b} = {subtract(args.a, args.b)}")


if __name__ == '__main__':
    main()                     # 仅直接运行时执行，被导入时不执行

# 直接运行
python calculator.py 3 + 5
# 输出: 3.0 + 5.0 = 8.0

# 被导入时不会触发 main()
# import calculator → calculator.add(1, 2) → 3

#!/usr/bin/env python3
"""演示模块命名空间的隔离效果"""

# module1.py 的内容等价于：
import types
module1 = types.ModuleType('module1')
module1.x = 10
module1.func = lambda: "Hello from module1"

# module2.py 的内容等价于：
module2 = types.ModuleType('module2')
module2.x = 20
module2.func = lambda: "Hello from module2"

# 同名变量互不干扰
print(module1.x)                      # → 10
print(module2.x)                      # → 20

# 同名函数互不干扰
print(module1.func())                 # → Hello from module1
print(module2.func())                 # → Hello from module2

# module_a.py
import module_b                       # 导入 module_b

def func_a():
    return module_b.func_b()          # 调用 module_b 的函数

# module_b.py
import module_a                       # 导入 module_a → 循环！

def func_b():
    return module_a.func_a()          # 调用 module_a 的函数

# module_a.py

def func_a():
    from module_b import func_b       # 延迟到调用时才导入
    return func_b()

# 重构前：a ↔ b（循环）
# 重构后：a → base ← b（无循环）

base.py    # 存放两者都需要的公共定义
module_a.py  # import base（不 import module_b）
module_b.py  # import base（不 import module_a）

# module_a.py
import module_b                       # 顶层导入，但不立即使用

def func_a():
    return module_b.func_b()          # 函数内使用（此时 module_b 已加载完毕）

# 不好的设计：Controller ↔ Model 循环依赖
# 好的设计：Controller → Model，Model 通过回调/事件通知 Controller

#!/usr/bin/env python3
"""模块相关内置函数演示"""

import math
from importlib import reload

# dir()：查看模块所有属性
print(dir(math))                      # ['__doc__', '__file__', 'acos', ...]

# help()：查看帮助文档
# help(math.sqrt)                    # 显示 sqrt 的详细说明

# vars()：查看模块命名空间字典
print(vars(math).keys())              # 等价于 math.__dict__.keys()

# reload()：重新加载模块（调试时有用）
# 注意：reload 参数必须是已导入的模块对象，不是字符串
my_module = __import__('math')        # 获取模块对象
reload(my_module)                     # 重新加载

#!/usr/bin/env python3
"""理解 __pycache__ 机制"""

import my_module                      # 首次导入：编译 → 保存 .pyc → 执行
import my_module                      # 再次导入：直接加载 .pyc（更快）

# 何时需要清理 __pycache__？
# 1. 修改了 Python 版本（字节码不兼容）
# 2. 修改了源文件的时间戳但内容没变（极少见）
# 3. 部署时为了减小体积

# 命令行清理
# find . -type d -name __pycache__ -exec rm -rf {} +
# 或
# pyclean .

#!/usr/bin/env python3
"""动态导入模块示例"""

import importlib

# ── 方式 1：import_module ────────────────────────────────────
module_name = "math"                              # 模块名可以是变量
mod = importlib.import_module(module_name)        # 等价于 import math
print(mod.sqrt(16))                               # → 4.0

# ── 方式 2：导入子模块 ───────────────────────────────────────
path_mod = importlib.import_module("os.path")     # 等价于 import os.path
print(path_mod.join("dir", "file.txt"))           # → dir/file.txt

# ── 方式 3：插件模式 ─────────────────────────────────────────
# 根据配置加载不同的数据库驱动
db_drivers = {
    "mysql": "pymysql",
    "postgres": "psycopg2",
    "sqlite": "sqlite3",
}

config = "sqlite"                                 # 可从配置文件读取
driver_name = db_drivers[config]
driver = importlib.import_module(driver_name)
print(f"已加载驱动: {driver_name}")

# ── 方式 4：安全导入（处理模块不存在的情况）────────────────────
def safe_import(module_name: str):
    """安全导入模块，不存在时返回 None"""
    try:
        return importlib.import_module(module_name)
    except ModuleNotFoundError:
        print(f"模块 {module_name} 未安装，请运行: pip install {module_name}")
        return None

optional = safe_import("nonexistent_module")      # → 模块 nonexistent_module 未安装...

#!/usr/bin/env python3
"""ModuleNotFoundError 排查清单"""

import sys

# 1. 检查模块是否已安装
# pip list | grep module_name

# 2. 检查模块是否在搜索路径中
for p in sys.path:
    print(p)                                    # 确认模块所在目录是否在其中

# 3. 检查是否在虚拟环境中
import os
print(sys.executable)                           # 确认使用的 Python 解释器路径
print(os.environ.get('VIRTUAL_ENV', '未激活虚拟环境')

# 4. 常见原因：
# - 拼写错误：import maths → import math
# - 未安装：pip install module_name
# - 虚拟环境不对：确认在正确的 venv 中
# - 目录不在 sys.path 中：添加到 PYTHONPATH 或调整项目结构

# 错误
python my_package/sub_package/module_b.py

# 正确
python -m my_package.sub_package.module_b

import math                         # 在当前命名空间创建名称 math → 指向模块对象
# 使用：math.sqrt(9)

from math import sqrt               # 在当前命名空间创建名称 sqrt → 指向函数对象
# 使用：sqrt(9)

# 本质区别：绑定的对象不同
# import x 绑定的是模块对象
# from x import y 绑定的是模块内的属性对象

import math
print(math.__file__)                # 模块源文件路径（内置模块无此属性）

import json
print(json.__file__)                # .../json/__init__.py

1. sys.modules          → 已缓存模块
2. 内置模块              → built-in modules
3. sys.path[0]          → 当前脚本目录
4. PYTHONPATH           → 环境变量
5. 标准库目录            → Python 安装目录
6. site-packages        → 第三方包安装目录

my_project/
├── pyproject.toml        # 项目配置和依赖
├── README.md             # 项目说明
├── src/
│   └── my_package/
│       ├── __init__.py   # 包初始化，可暴露公共 API
│       ├── core.py       # 核心功能
│       ├── utils.py      # 工具函数
│       └── subpackage/   # 子包
│           ├── __init__.py
│           └── helpers.py
├── tests/                # 测试目录
│   ├── __init__.py
│   └── test_core.py
└── docs/                 # 文档目录