一个运营后台的「最近七天」统计总是少八小时,查到最后不是查询写错,而是时间根本没带时区。代码里用 datetime.now() 取本地时间,存进数据库时又被当成 UTC,展示时再按本地时间加一遍,两边一错,数据就整体偏移。

同一周还有一个接口问题:前端收到的是 {"\u540d\u5b57": "\u5f20\u4e09"},用户看到一屏转义字符。后端只是调了 json.dumps,没意识到默认会把非 ASCII 字符全部转义。两个问题都不复杂,但都需要知道 API 的默认值是什么。

这篇把日常最常用的五组标准库过一遍:字符串、集合容器、datetime、json、pathlib。不追求覆盖所有方法,只讲最常用、最容易用错的那些,并且给出本机跑出来的真实输出。

字符串:切分、清理与拼接

字符串是不可变对象,所有「修改」方法都返回新字符串,原对象不变。这个前提决定了两个习惯:链式调用可以放心写,但循环里反复拼接会产生大量中间对象。

s = "  ERROR  disk  "
print(repr(s.strip()))
print("a,b,,c".split(","))
print("a\nb\n".splitlines())
print("-".join(["2026", "11", "07"]))

输出:

'ERROR  disk'
['a', 'b', '', 'c']
['a', 'b']
2026-11-07

strip() 只去掉两端空白,不会动中间的两个空格;split(",") 保留空字段,得到四个元素;splitlines() 按行切,并且不会在末尾留下空字符串。split() 不传参数时按任意空白切,并且会合并连续空白,这和 split(" ") 的行为不同,解析用户输入时经常需要前者。

取前后缀用 removeprefix 和 removesuffix,不要用 strip 代替。解析文件名时写 "report.csv".strip(".csv"),得到的是 "report",看起来对;换成 "csvdata.csv" 就会把开头的 csv 也削掉,得到 "data"。strip 的参数是「字符集合」,不是「完整字符串」。正确写法是 name.removesuffix(".csv"),语义清楚,也不会误伤中间内容。切片则适合按下标取固定位置,line[:10] 取前十列,line[::-1] 反转,但别在长文本里反复切片拼装。

拼接首选 join,因为它只分配一次结果字符串。用 + 在循环里拼 n 段文本,中间会产生 n 个临时对象,数据量大时差距明显。格式化首选 f-string,f"{name}: {count:,}" 能直接加千分位,f"{value:.2f}" 控制小数位。

大小写转换要注意语言差异。lower() 对德语的 ß 不会变成 ss,而 casefold() 会,后者才是「不区分大小写比较」的正确选择。反过来,土耳其语的 İ 在 lower() 下会变成 i 加一个组合点,长度都变了。做用户名校验、搜索匹配时,如果只处理英文,lower() 够了;要处理多语言,casefold() 更稳。

str.replace(old, new, count) 的第三个参数是「最多替换几次」,不是「替换到第几个」。不传就全部替换。想只改第一处,传 1,实际输出里 "abcabc".replace("a", "x", 1) 得到 xbcabc。

集合容器:列表、字典、集合各管什么

Python 内置的容器各有明确的用途。列表保持插入顺序、允许重复、支持下标,适合「有序的一批东西」;元组不可变,适合当记录或字典的键;字典按键存取,保持插入顺序;集合只保证元素唯一,不保证顺序,适合去重和成员判断。

成员判断的复杂度差别很大:x in list 要逐个比较,数据量大时是线性时间;x in set 走哈希,平均常数时间。十万条数据里反复判断某个值在不在,用列表会明显卡,换成集合立刻下来。代价是集合要额外内存,而且元素必须可哈希,列表和字典不能直接放进去。

print({1, 2} | {2, 3})
print({1, 2} & {2, 3})
print({1, 2} - {2, 3})
{1, 2, 3}
{2}
{1}

并集、交集、差集的运算符比方法名 union、intersection、difference 短,但注意 - 是「在左边不在右边」,方向不能反。集合还支持 issubset、issuperset,做权限比对时比手写循环清楚。

collections 里有三个常用工具。Counter 直接统计频次,most_common(n) 取前几名;defaultdict(list) 让「键不存在就自动建空列表」这件事不用每次都写判断;deque 是双端队列,两头增删都是常数时间,设了 maxlen 之后自动丢弃旧元素,适合保留「最近 N 条」。

c = collections.Counter("abracadabra")
print(c.most_common(2))

d = collections.defaultdict(list)
for k, v in [("a", 1), ("a", 2), ("b", 3)]:
    d[k].append(v)
print(dict(d))

dq = collections.deque([1, 2, 3], maxlen=3)
dq.append(4)
print(dq)
[('a', 5), ('b', 2)]
{'a': [1, 2], 'b': [3]}
deque([2, 3, 4], maxlen=3)

字典本身保持插入顺序,这一点在 Python 3.7 之后是语言保证,不是实现细节。但不要依赖「遍历顺序等于业务顺序」去写逻辑,除非那个顺序确实由你控制。需要明确排序时,用 sorted(d.items(), key=lambda kv: kv[1]) 写出来,别让读者猜。

取值时优先用 d.get(key, default),而不是 d[key] 再捕获 KeyError。前者适合「缺失是正常情况」,后者适合「缺失说明数据有问题、应该暴露」。两者没有绝对优劣,关键是想清楚「键不存在」在这个位置是异常还是常态。配置文件读取通常用 get 加默认值,内部数据结构之间的传递则应该用 [],让缺失尽早炸出来,别让默认值掩盖上游的 bug。

d.keys()、d.values()、d.items() 返回的是视图,不是列表。视图会跟着字典变化,遍历时如果同时增删键,会抛 RuntimeError: dictionary changed size during iteration。要边遍历边改,先 list(d.items()) 复制一份,或者先收集要删的键,循环结束后统一删。这个报错在「清理过期缓存」的代码里很常见,原因不是字典坏了,是迭代器发现长度变了。

datetime:不带时区的时间是个半成品

datetime 对象分两种:naive(天真的)和 aware(带时区的)。naive 对象只记录年月日时分秒,不记录这是哪个时区的时间,所以它无法准确对应到某一个时刻。aware 对象带 tzinfo,能换算成 UTC,也能比较。

now = dt.datetime.now(dt.timezone.utc)
print(now.isoformat(timespec="seconds"))
print(dt.datetime.strptime("2026-11-07 12:30", "%Y-%m-%d %H:%M"))
print(now + dt.timedelta(days=1, seconds=-30))
2026-11-06T23:49:26+00:00
2026-11-07 12:30:00
2026-11-07 23:48:56.767393+00:00

存储和传输统一用 UTC 的 aware 时间,展示时再转成用户所在时区。这样做的好处是:数据库里只有一种时间,跨时区排序和比较不会错;前端拿到 ISO 8601 字符串后自己按本地时区渲染。strptime 解析出来的是 naive 对象,要补时区就用 replace(tzinfo=...) 或者 astimezone,别让它裸着进数据库。

格式化字符串里的 %m 是月、%M 是分,%H 是 24 小时制、%I 是 12 小时制,大小写写反不会报错,只会安静地输出错时间。我见过把 %M 写成 %m 的日志,月份那一列全是分钟数,查了两天才发现。解析用户输入时,别用 strptime 硬猜十几种格式,先让输入方统一成 ISO 8601,或者用 datetime.fromisoformat,它对带时区的字符串支持很好。

datetime.utcnow() 在较新版本里已经标记为弃用,我本机跑的时候直接给出 DeprecationWarning,提示改用 datetime.now(datetime.UTC)。弃用的原因正是它返回 naive 对象,容易被误当成其他时区的时间。新代码不要再写 utcnow。

带时区换算绕不开 IANA 时区库。在 Linux 上系统通常自带;在 Windows 上我实测 ZoneInfo("Asia/Shanghai") 直接抛 ZoneInfoNotFoundError: 'No time zone found with key Asia/Shanghai',因为系统没有时区数据,需要额外安装 tzdata 包。这一点对「本机开发正常、服务器报错」或反过来的情况都适用,部署时要把时区数据当成依赖写进环境说明。

采集入口就转成 aware UTC:datetime.now(timezone.utc)。
存储数据库字段统一存 UTC,写入前确认没有 naive 对象混进来。
展示按用户时区转换后再格式化,接口传 ISO 8601 字符串。

timedelta 只做「时长」加减,不处理夏令时。跨夏令时的「明天上午九点」不能简单加一天,要用日历库或先转成本地时区的 aware 时间再算。中国目前不实行夏令时,但代码如果面向多地区用户,这个边界迟早会遇到。

json:默认值决定了你看到什么

json.dumps 的默认行为有两个容易忽略:非 ASCII 字符会被转成 \uXXXX,键按插入顺序输出。前者让中文在接口里变成转义序列,后者让同样的数据在不同代码路径下产生不同文本,不利于缓存和比对。

obj = {"名字": "张三", "分数": 0.1}
print(json.dumps(obj))
print(json.dumps(obj, ensure_ascii=False, sort_keys=True))
{"\u540d\u5b57": "\u5f20\u4e09", "\u5206\u6570": 0.1}
{"分数": 0.1, "名字": "张三"}

对外的中文接口一般写 ensure_ascii=False,同时保证响应头里 charset=utf-8。需要稳定输出(比如签名、缓存键、配置文件)时加 sort_keys=True,让键顺序固定。indent 只影响可读性,机器传输不要开,体积会变大。

datetime 不是 JSON 原生类型,直接序列化会报 TypeError: Object of type datetime is not JSON serializable。要么在编码前转成 ISO 字符串,要么给 default 参数传一个转换函数。default 只在遇到不认识的对象时调用,返回可序列化的值,不会递归处理嵌套的自定义对象,复杂结构要在业务层先转成字典。

解析端也要有心理准备:json.loads 把整数解析成 int、小数解析成 float、对象解析成 dict,没有类型标注,也没有日期类型。接口约定里的「金额是字符串」如果对方传了数字,你这边不会报错,只会在后续计算里出现精度差异。金额、长整数 ID 这类值,建议在 JSON 里用字符串传,避免经过浮点或超出安全整数范围。解析后先做一次字段和类型检查,再进入业务。

还有一个标准兼容问题:json.dumps(float("nan")) 会输出 NaN,json.loads("NaN") 也能读回来,但 NaN 不是合法 JSON,其他语言的解析器可能直接拒绝。跨语言接口里要禁用 allow_nan,或者在源头保证不产生 NaN。

不要用 eval 解析任何来路不明的「JSON」。json.loads 只认 JSON 语法,不会执行代码;eval 会。两者看起来都能把字符串变成对象,安全性差一个数量级。

大文件不要一次 load。标准库没有流式解析器,几十 MB 还能接受,上 GB 就要换方案:按行读取的 JSON Lines 格式,或者用第三方流式解析库。这一点和下一篇的文件读取直接相关。

如果数据是「一行一个 JSON」,处理方式会简单很多:逐行读取,每行单独 json.loads,坏行单独记录并跳过,内存里永远只有一行。这种格式在日志、事件流、批量导入里很常见。缺点是整个文件不是合法 JSON,不能直接被某些工具读取;优点是坏了哪一行一目了然,不用面对一个几百 MB 的数组。选格式时先想清楚「谁读、怎么读、坏了怎么修」,比只看体积重要。

pathlib:把路径当对象

以前拼路径用 os.path.join,处理后缀、取文件名、判断存在都要调不同函数。pathlib.Path 把这些收进一个对象,用 / 运算符拼接,跨平台自动处理分隔符。

base = pathlib.Path(tempfile.gettempdir()) / "langdocs-api"
base.mkdir(exist_ok=True)
f = base / "data.json"
f.write_text(json.dumps(obj, ensure_ascii=False), encoding="utf-8")
print(f.name, f.stem, f.suffix)
print(f.with_suffix(".txt").name)
print([p.name for p in base.glob("*.json")])
data.json data .json
data.txt
['data.json']

name 是带后缀的文件名,stem 是去掉最后一个后缀的部分,suffix 是最后一个后缀。with_suffix 替换后缀,with_name 替换整个文件名。glob("*.json") 只匹配当前目录,递归要用 rglob。这些方法都返回新对象,不修改原对象。

相对路径和绝对路径要分清。Path("data.json") 是相对路径,它相对于「当前工作目录」,不是相对于脚本文件所在目录。用 python scripts/job.py 启动时,工作目录是项目根目录;用绝对路径启动时,工作目录可能是别处,同一个相对路径就指向不同文件。需要「相对于脚本」的路径,用 Path(__file__).resolve().parent / "data.json"。resolve() 还会展开 .. 和符号链接,代价是要访问文件系统,文件不存在时旧版本可能报错,新版本默认更宽松。

遍历目录用 iterdir() 或 glob(),注意它们默认包含子目录。处理上传目录时,经常需要跳过隐藏文件和临时文件,判断要写在循环里:if p.is_file() and not p.name.startswith(".")。删除文件用 unlink(),删除空目录用 rmdir(),递归删除要 shutil.rmtree(),这个操作不可恢复,路径变量最好先打印确认。

read_text 和 write_text 是便捷方法,但必须显式传 encoding="utf-8"。不传就用系统默认编码,在 Windows 上可能是 GBK,在 Linux 上可能是 UTF-8,同一份代码换台机器就可能读错。下一篇会专门讲编码问题,这里先记住:涉及文本文件,编码永远写出来。

exists() 这类检查有竞态:检查完到真正打开之间,文件可能被删掉。安全做法是直接操作并捕获异常,而不是先检查再操作。我实测读一个不存在的文件,抛出的 FileNotFoundError 里带 filename 和 errno=2,比一句「文件不存在」有用得多。

现象对照

现象真实原因第一步查什么
接口里的中文变成 \u5f20\u4e09json.dumps 默认 ensure_ascii=True加 ensure_ascii=False,确认响应编码
统计时间整体差八小时naive 时间被当成 UTC 或本地时间混用打印 tzinfo,确认采集、存储、展示三段是否统一 UTC
utcnow() 出现弃用警告返回 naive 对象,语义不明确改用 datetime.now(timezone.utc)
Windows 上 ZoneInfo 找不到时区系统缺少 IANA 时区数据安装 tzdata 包,确认部署环境一致
datetime 序列化报 TypeErrorJSON 不认识 datetime 类型先转 ISO 字符串,或用 default 参数
同样的字典序列化结果不一样键顺序随插入顺序变化需要稳定输出时加 sort_keys=True
成员判断在大列表上很慢列表查找是线性时间换成集合,确认元素可哈希
换台机器读文件编码就错依赖系统默认编码所有文本读写显式传 encoding
文件明明存在却报不存在检查与打开之间有竞态去掉「先检查再打开」,直接捕获异常

边界与代价

标准库的优点是「不用装、到处有」,代价是它只提供通用能力,不替你做业务决策。时间用 naive 还是 aware、字符串用 lower 还是 casefold、JSON 要不要转义中文,这些默认值都摆在那里,选错了不会报错,只会在某个边界上出问题。

集合容器也一样。列表、字典、集合的复杂度差异在数据量小时看不出来,到了十万、百万级才显形。写代码时多问一句「这个容器后面会装多少条、我要做什么操作」,比事后性能优化便宜。需要「既快又有序」时,字典和集合的组合通常够用,不必一上来就引入第三方数据结构库。

datetime 的复杂度来自现实世界本身:时区规则会变,夏令时会调整,历史时间还有各种特例。标准库能处理常见场景,但涉及日历计算、重复事件、跨时区排班,就需要更专门的库。不要用 timedelta(days=1) 硬算「明天同一时刻」,那是「加 24 小时」,不是「加一天」。

pathlib 的代价主要在旧代码兼容上。很多库仍然接受字符串路径,Path 对象大多数时候能直接传,遇到不认的类型再 str(p) 转换。跨平台时注意 Windows 的盘符、UNC 路径和大小写不敏感,别在代码里硬编码分隔符。

json 的边界是「它只是数据格式,不是schema」。解析出来的字典没有类型保证,字段缺失、类型变化都要自己校验。对外接口要在边界处做一次结构检查,别让脏数据流进业务深处才炸。

小结

字符串操作记住「不可变、返回新对象」,切分用 splitlines 和 split 分清场景,拼接用 join;容器按「要不要顺序、要不要去重、要不要快速查找」选,统计用 Counter,分组用 defaultdict,滑动窗口用 deque;时间统一用带时区的 UTC,存储和展示分开;JSON 注意 ensure_ascii、sort_keys 和 datetime 序列化;路径用 pathlib,文本读写永远写编码。

这些 API 单看都不难,难在默认值和边界。把默认值当成「设计选择」而不是「随便这样」,用错的地方会少很多。遇到不确定的行为,先写十行代码验证,再下结论。

当天可以自己验证的练习:

  1. 构造一个含中文和浮点的字典,分别用默认参数和 ensure_ascii=False 序列化,对比输出字节数。
  2. 用 datetime.now() 和 datetime.now(timezone.utc) 各取一次时间,打印 tzinfo 并做减法,观察报错或结果。
  3. 在 Windows 上试 ZoneInfo("Asia/Shanghai"),记录报错,再安装 tzdata 后重试。
  4. 用 Counter 统计一段文本的字符频次,取前三名,再用普通字典手写一遍对比代码量。
  5. 用 pathlib 列出某个目录下所有 .py 文件,打印文件名、主名和后缀,再用 rglob 递归一次。

下一篇讲读取文件:文本、二进制、编码与异常。这一篇里已经埋了几个伏笔:默认编码、FileNotFoundError、大文件不能一次读完。下一篇把它们展开,讲清一次 open 背后到底发生了什么。