Python函数-模块

一、模块和包

1、概念

• 模块（module） 就是一个 .py 文件；
• 包（package） 是含 __init__.py 的目录，可嵌套子包；
• import 的本质是按 搜索路径 找到模块/包，把它变成 对象 放到当前命名空间。

2、文件结构示例

myproj/                 # 项目根
├── mypkg/              # 包
│   ├── __init__.py     # 包初始化（可为空）
│   ├── mod_a.py        # 模块
│   └── subpkg/         # 子包
│       ├── __init__.py
│       └── mod_b.py
└── main.py             # 主脚本

3、搜索顺序（sys.path）

1. 当前脚本所在目录
2. PYTHONPATH 环境变量
3. 标准库目录
4. site-packages（第三方包）

import sys
print(sys.path)

拓展：添加指定路径

3.1、四种方法速查表

3.2、逐条说明与示例

3.2.1、运行时修改 sys.path（最灵活）

项目结构：

myproj/                 # 项目根
├── commons/            # 包
│   ├── __init__.py     # 包初始化（可为空）
│   ├── mod_a.py        # 模块
│   └── subpkg/         # 子包
│       ├── __init__.py
│       └── mod_b.py
└── bin/
    ├── __init__.py
    └── run.py          # 项目执行文件

import os
import sys

sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

• 优点：无需重启解释器，可动态计算路径。
• 缺点：只对当前进程有效；写在脚本里别人看不到。

3.2.2、环境变量 PYTHONPATH（开发常用）

• Linux/macOS：

export PYTHONPATH=$HOME/projects/toolkit:$PYTHONPATH
python script.py

• Windows PowerShell：

$Env:PYTHONPATH = "C:\projects\toolkit;$Env:PYTHONPATH"

• 优点：一次设置，当前终端及其子进程均可 import toolkit。
• 缺点：换终端/IDE 需重新设置；发布给他人不方便。

3.2.3、.pth 文件（“一次配置，永久生效”）

1. 找到当前解释器的 site-packages 目录：

   import site, pathlib
   print(pathlib.Path(site.getsitepackages()[0]) / "my_extra.pth")

2. 新建 my_extra.pth，内容只需一行：/absolute/path/to/your/dir

3. 保存后任何新启动的该解释器都会自动把目录加入 sys.path。

• 优点：跨项目、跨终端生效；无需改动代码。
• 缺点：需要写文件权限；路径为绝对路径。

3.2.4、包内相对导入 + 开发安装（推荐用于正式项目）

项目结构：

myproj/
├── pyproject.toml
└── mypkg/
    ├── __init__.py
    └── utils.py

pyproject.toml 最少内容：

[project]
name = "mypkg"
version = "0.1.0"

安装到当前虚拟环境：

cd myproj
python -m pip install -e .

• 效果：mypkg 被“链接”到 site-packages，任何路径下都能 import mypkg。
• 优点：符合打包规范，可发布。
• 缺点：需要简单打包描述，但现代工具（Poetry、PDM、Hatch）已极大简化。

4、导入包的方法

5、导入模块的方法

6、绝对 vs 相对导入

from .subpkg import mod_b      # 相对导入
import mypkg.subpkg.mod_b      # 绝对导入

7、常见坑 & 修复

8、执行入口（主函数）

8.1、基本语法

def main():
    # 主要的程序逻辑
    print("这是主函数")

if __name__ == "__main__":
    main()

8.2、__name__ 变量的作用

• 当 Python 文件被直接运行时，__name__ 的值为 “__main__”
• 当 Python 文件被导入为模块时，__name__ 的值为模块名（文件名）

def helper_function():
    """一个辅助函数"""
    print("辅助函数被调用")

def main():
    """主函数，程序的入口点"""
    print("程序开始执行")
    helper_function()
    print("程序执行结束")

# 这是标准的执行入口检查
if __name__ == "__main__":
    main()

二、第三方模块

1、什么是“第三方模块”

• 标准库：Python 官方随解释器一起发布的模块，如 os、json、datetime 等。
• 第三方模块（third-party packages）：由社区或个人开发、托管在 PyPI（Python Package Index）上的模块/包，需要用户额外安装才能使用，如 requests、numpy、pandas、flask、django 等。
• 本质：放在 site-packages 目录下的目录或 .whl/.tar.gz 安装包，包含模块代码和元数据（METADATA、setup.py、pyproject.toml 等）。

2、常用安装方式

2.1、pip（99 % 场景）

• 概念：官方包管理器，自动下载 → 选 wheel → 回退源码 → 编译（如需要）。

• 常用命令：

  # 安装
  python -m pip install 包名
  # 指定版本
  python -m pip install "包名>=1.2,<2.0"
  # 升级
  python -m pip install -U 包名
  # 卸载
  python -m pip uninstall 包名
  # 根据锁文件批量安装
  python -m pip install -r requirements.txt
  # 离线：先下载再装
  python -m pip download -d wheelhouse -r requirements.txt
  python -m pip install --no-index --find-links wheelhouse -r requirements.txt

2.2、wheel（二进制包，后缀 .whl）

• 概念：已编译好的“快递包裹”，复制即可用，跨平台需 tag 匹配。

• 常用命令：

  # 直接装本地 wheel
  python -m pip install somepkg-1.0-cp312-cp312-win_amd64.whl
  # 自己打包 wheel
  python -m build          # 生成 dist/*.whl
  twine upload dist/*      # 推到 PyPI

2.3、源码（sdist，.tar.gz / .zip）

• 概念：最原始压缩包，任何平台都能编；缺 wheel 或需要改代码时用。

• 常用命令：

  # 1、解压
  tar -xf package-1.0.tar.gz
  cd package-1.0
  
  # 2、构建（可选，setup.py 会自动 build）
  python setup.py build
  
  # 3、安装
  python setup.py install          # 全局
  python setup.py install --user   # 仅当前用户

2.4、Conda（科学计算全家桶）

• 概念：带 C/Fortran/CUDA 依赖的大型二进制仓库，与 pip 互不干扰。

• 常用命令：

  conda install numpy
  conda install pytorch torchvision -c pytorch
  # 导出/恢复环境
  conda env export > env.yml
  conda env create -f env.yml

2.5、系统包管理器（apt/yum/brew）

• 概念：操作系统层面的 Python 包，版本通常滞后，但和系统库耦合。

• 常用命令：

  sudo apt install python3-numpy
  sudo yum install python3-lxml
  brew install python-tkinter

2.6、私有源 / Git / 本地路径

# Git 直接装
python -m pip install git+https://github.com/user/proj.git@main
# 私有 PyPI
python -m pip install --extra-index-url https://pypi.company.com/simple 私有包
# 本地目录
python -m pip install ./myproject

3、注意事项

1. 使用虚拟环境（venv、conda env、poetry、pipenv）避免包冲突。

2. 国内用户建议配置镜像：

   pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
   
   # 也还有其他的源可供选择（豆瓣应用广泛）
   豆瓣：https://pypi.douban.com/simple/
   阿里云：http://mirrors.aliyun.com/pypi/simple/
   中国科技大学：https://pypi.mirrors.ustc.edu.cn/simple/
   清华大学：https://pypi.tuna.tsinghua.edu.cn/simple/
   中国科学技术大学：http://pypi.mirrors.ustc.edu.cn/simple/

3. 部分带 C 扩展的包（如 numpy, lxml）在 Windows 上推荐直接用 pip 下载预编译 wheel；若失败，可改用 conda。

4. 如果同时装了 Python2/3，使用 python3 -m pip 或 py -3 -m pip 明确版本。

三、内置模块

1、语言基础 & 运行时

1.1、sys

作用：与 Python 解释器交互。

import sys
sys.argv        # 命令行参数列表
sys.exit(1)     # 立即终止进程
sys.path        # 模块搜索路径
sys.stderr.write('error\n')

1.2、builtins（隐式加载）

作用：存放所有内建函数/异常；可覆盖或增强。

__builtins__.len([1,2,3])  # 直接访问

1.3、gc

作用：手动控制垃圾回收。

import gc
gc.collect()          # 立即回收
gc.disable()          # 关闭自动回收

2、数据类型增强

2.1、collections

作用：高性能容器数据类型。

from collections import Counter, defaultdict, deque
Counter('abracadabra')           # 计数
d = defaultdict(list); d['a']    # 默认空列表
dq = deque(maxlen=5)             # 双端队列

2.2、itertools

作用：迭代器“工具箱”，惰性求值，节省内存。

from itertools import chain, islice, groupby
list(chain([1,2], [3,4]))        # 扁平化
for k, g in groupby('AAABBB'):   # 分组
    print(k, list(g))

3、文本处理

3.1、re

作用：正则表达式。

import re
m = re.search(r'(\d{4})-(\d{2})', '2025-08')
m.group(1)                       # '2025'
re.sub(r'\s+', ' ', text)        # 压缩空格

3.2、string / textwrap / unicodedata

作用：

• string 提供常量和简单工具处理 ASCII 文本
• textwrap 负责按宽度优雅地换行与缩进多行文本
• unicodedata 让你查询和转换 Unicode 字符的规范化形式与属性。

import string, textwrap, unicodedata
string.ascii_letters               # 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
textwrap.fill(s, width=40)         # 自动换行
unicodedata.name('A')              # 'LATIN CAPITAL LETTER A'

4、二进制 & 编码

4.1、struct

作用：在 bytes 与 C 结构体之间转换。

import struct
struct.pack('>hhl', 1, 2, 3)     # 打包成字节
struct.unpack('f', b'\x40\x49\x0f\xdb')[0]  # 解包 float

4.2、base64 / binascii / codecs

作用：

• base64 用可打印 ASCII 编解码二进制
• binascii 在二进制与十六进制（及 Base64/32/16）间快速转换并校验校验和
• codecs 注册并流式处理各种文本编码的编解码与增量转换。

import base64, codecs
base64.b64encode(b'binary')        # b'YmluYXJ5'
codecs.encode('hello', 'rot_13')   # 'uryyb'

5、文件 & 目录 I/O

5.1、os / os.path / pathlib

作用：操作系统接口与路径。

import os, pathlib
os.listdir('.')
pathlib.Path('foo/bar').mkdir(parents=True, exist_ok=True)
os.path.join('root', 'file.txt')

5.2、shutil

作用：高级文件操作（复制、打包、删除树）。

import shutil
shutil.copy('src.py', 'dst.py')
shutil.make_archive('proj', 'zip', root_dir='.')

5.3、glob / fnmatch

作用：文件通配符匹配。

import glob
glob.glob('*.py')                # 当前目录所有 py

6、进程 & 并发

6.1、subprocess

作用：启动子进程并与其通信。

import subprocess
out = subprocess.check_output(['ls', '-l'])
subprocess.run(['python', '-m', 'pip', 'install', 'tqdm'])

6.2、threading / concurrent.futures

作用：线程与线程池。

from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor() as ex:
    ex.map(download, urls)

6.3、multiprocessing

作用：多进程并行，绕过 GIL。

from multiprocessing import Pool
with Pool() as p:
    p.map(cpu_intensive, data)

7、日期 & 时间

7.1、datetime / time / calendar

作用：日期时间运算、格式化、本地化。

from datetime import datetime, timedelta
now = datetime.now()
(now + timedelta(days=7)).strftime('%Y-%m-%d %H:%M')

8、数学 & 统计

8.1、math / cmath

作用：浮点数学（math）与复数（cmath）。

import math
math.sqrt(2); math.isclose(0.1+0.2, 0.3)

8.2、random / secrets

作用：伪随机与安全随机。

import random, secrets
random.choice(['♠','♥','♦','♣'])
secrets.token_hex(16)            # 32 位安全令牌

8.3、decimal / fractions / statistics

作用：高精度十进制、分数、统计量。

from decimal import Decimal
Decimal('0.1') + Decimal('0.2')  # Decimal('0.3')
from statistics import mean, median
mean([1,2,3,4])

9、数据序列化 & 持久化

9.1、json / csv / configparser

作用：轻量结构化数据交换。

import json, csv
json.dumps(obj, ensure_ascii=False, indent=2)
with open('data.csv') as f:
    for row in csv.DictReader(f):
        print(row)

9.2、pickle / shelve / sqlite3

作用：二进制对象持久化、嵌入式数据库。

import pickle, sqlite3
pickle.dump(obj, open('cache.pkl', 'wb'))
conn = sqlite3.connect('demo.db')
conn.execute('CREATE TABLE IF NOT EXISTS user(id INTEGER PRIMARY KEY, name TEXT)')

10、网络 & 互联网

10.1、urllib / http.client / smtplib / email

作用：HTTP 请求、构造邮件等。

from urllib.request import urlopen
html = urlopen('https://example.com').read().decode()

10.2、socket / ssl

作用：底层网络通信与安全套接字。

import socket, ssl
ctx = ssl.create_default_context()
with ctx.wrap_socket(socket.socket(), server_hostname='pypi.org') as s:
    s.connect(('pypi.org', 443))

11、调试 & 性能测试

11.1、logging

作用：标准日志系统，分级、可配置。

import logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')
logging.info('Started')

11.2、pdb / cProfile / timeit

作用：交互式调试、性能分析、小段代码计时。

python -m pdb script.py
python -m cProfile -s cumulative script.py
import timeit
timeit.timeit('sum(range(1000))', number=10000)