“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工具函数的命名、类型标注、异常和日志属于接口的一部分。外部服务的超时和重试次数做成参数，文件函数明确编码与覆盖策略，业务代码就不必跟着实现细节变化。
代码大全的边界
一次性脚本可以从片段开始；当代码进入多人协作、并发处理或关键数据写入阶段，就需要依赖锁定、自动化测试和发布流程。网上的代码片段是起点，不是经过你项目验证的生产组件。
真正可复用的代码，不是复制次数多，而是边界清楚、输入可检查、失败可定位。
