Python 代码大全：按场景整理可复用片段与工具函数

“python代码大全”类文章最容易变成代码堆：复制几段文件读写、HTTP 请求和列表处理，读者当下能跑，项目一变就不知道该改哪里。

更稳的做法是先按场景检索，再把高频片段收敛成有输入、有输出、有测试的工具函数。下面用 Python 标准库整理一套小型工具箱，示例代码没有伪造性能数据，复制后可以直接在本地验证。

先按场景整理片段

文件 I/O、网络请求、数据处理和调试测试，是项目里最常重复的四类逻辑。它们不应该混在一个 utils.py 里，而是先按职责分区。

图：从文件、网络、数据和调试四个入口，汇聚到可复用工具函数。

文件读写：编码和异常要显式

from pathlib import Path

def read_text(path: str | Path, encoding: str = "utf-8") -> str:
    file_path = Path(path)
    if not file_path.is_file():
        raise FileNotFoundError(f"文件不存在: {file_path}")
    return file_path.read_text(encoding=encoding)

def write_text(path: str | Path, content: str) -> None:
    file_path = Path(path)
    file_path.parent.mkdir(parents=True, exist_ok=True)
    file_path.write_text(content, encoding="utf-8")

读取失败直接抛出带路径的异常，写入前创建父目录。需要覆盖保护时，可以先写临时文件，再调用 Path.replace()。

网络请求：超时比“能返回”更重要

标准库 urllib 足够演示最小边界：

import json
from urllib.request import Request, urlopen

def get_json(url: str, timeout: float = 10.0) -> dict:
    request = Request(url, headers={"Accept": "application/json"})
    with urlopen(request, timeout=timeout) as response:
        if not 200 <= response.status < 300:
            raise RuntimeError(f"HTTP 状态异常: {response.status}")
        return json.loads(response.read().decode("utf-8"))

生产代码还要处理 HTTPError、URLError 和有限重试。不要对鉴权失败、参数错误等 4xx 响应盲目重试；访问第三方接口前也要确认授权和频率限制。

数据清洗：把空值规则写出来

from collections.abc import Iterable, Mapping

def clean_rows(rows: Iterable[Mapping], field: str) -> list[str]:
    result = []
    for row in rows:
        value = row.get(field)
        if value is None:
            continue
        text = " ".join(str(value).split())
        if text:
            result.append(text)
    return result

这个函数只做去空白和过滤缺失值，不偷偷去重。是否区分大小写、全角半角和重复项，应由业务层明确决定。

片段什么时候该提取成函数

同一段逻辑出现两次以上，就值得问三个问题：

• 变化的部分能否变成参数？
• 输入错误时，函数是否会尽早失败？
• 能否用一个最小测试固定结果？

图：重复逻辑经过参数提取、输入校验和最小测试后，再收入 tools 模块。

例如给 clean_rows() 加一个测试：

import unittest

class TestCleanRows(unittest.TestCase):
    def test_strip_and_skip_empty(self):
        rows = [{"name": "  Alice  "}, {"name": ""}, {}]
        self.assertEqual(clean_rows(rows, "name"), ["Alice"])

if __name__ == "__main__":
    unittest.main()

可以在保存为 test_tools.py 后运行：

python -m unittest -v test_tools.py

我没有在当前环境声称这条命令的耗时或覆盖率；成功信号应是测试进程返回码为 0，并显示测试通过。

目录怎么放，后续才好维护

project/
├── app.py
├── tools/
│   ├── files.py
│   ├── http.py
│   └── data.py
└── tests/
    └── test_tools.py

工具函数的命名、类型标注、异常和日志属于接口的一部分。外部服务的超时和重试次数做成参数，文件函数明确编码与覆盖策略，业务代码就不必跟着实现细节变化。

代码大全的边界

一次性脚本可以从片段开始；当代码进入多人协作、并发处理或关键数据写入阶段，就需要依赖锁定、自动化测试和发布流程。网上的代码片段是起点，不是经过你项目验证的生产组件。

真正可复用的代码，不是复制次数多，而是边界清楚、输入可检查、失败可定位。