左右键翻页;“连续阅读”展开整份;搜索可定位概念。
第1–11行:这份文件做什么,怎样启动
001 | """Download the MNIST archive used by Keras and export PNG images + labels.csv. 002 | 003 | Install: conda install numpy pillow 004 | Run: python prepare_mnist.py 005 | Preview: python prepare_mnist.py --limit 20 --output mnist_preview 006 | 007 | The NPZ archive is the official Keras redistribution, not the original IDX files. 008 | Dataset and hash source: 009 | https://github.com/keras-team/keras/blob/master/keras/src/datasets/mnist.py 010 | """ 011 |
左侧看代码,右侧逐行讲解。
这份程序读取 Keras 使用的 MNIST .npz 归档,把数据变成可打开的 PNG 图片和标签表。课程文件是 prepare_mnist.txt,将内容另存为 prepare_mnist.py 后,从该文件所在目录的终端运行。
- 第1、7–10行用三引号包住模块说明,内容交代归档来源、以及该 NPZ 是 Keras 的分发版本。Python 将这段文字存为
__doc__,第70行用它生成命令行帮助。 - 第3–5行列出终端命令。
conda install numpy pillow安装处理数组与图片的工具;python prepare_mnist.py执行脚本并完整导出;带参数的命令只导出每个子集的前 20 张。
python prepare_mnist.py --limit 20 --output mnist_preview
运行这条命令时,程序仍取得并读取完整归档,随后在 mnist_preview/train/images/ 和 mnist_preview/test/images/ 各写 20 张普通 PNG。每个子集有自己的 labels.csv。根目录还会多出第一张训练图的放大版和像素表。
第12–22行:导入各项工具
012 | from pathlib import Path 013 | from urllib.request import urlopen 014 | import argparse 015 | import csv 016 | import hashlib 017 | import shutil 018 | 019 | import numpy as np 020 | from PIL import Image 021 | 022 |
左侧看代码,右侧逐行讲解。
第12–20行给后续代码准备工具。先看工具在哪里第一次真正做事,再回头读名字。
| 行号 | 导入的名字 | 后面负责的操作 |
|---|---|---|
| 12 | Path |
Path("data") / "images" 拼出 data/images,也能开文件、检查是否存在 |
| 13 | urlopen |
第42行打开归档的下载响应 |
| 14 | argparse |
第70–75行登记并读取 --input、--output、--limit |
| 15 | csv |
第58–64行创建写入器,写表头和图像标签 |
| 16 | hashlib |
第29–33行计算归档字节的 SHA-256 摘要 |
| 17 | shutil |
第43行把下载响应中的字节复制到磁盘文件 |
| 19 | numpy as np |
第83行用 np.load(...) 读取 NumPy 归档 |
| 20 | Image |
第63行用 Image.fromarray(...) 将像素数组保存为图片 |
from ... import ... 导入的名字可以直接写,例如 Path(...)、Image.fromarray(...)。import numpy as np 把整个模块取了短名,后续成员要通过 np.名字 引用。PIL 是 Pillow 安装包在代码中的导入名。
第23–27行:下载地址、固定摘要和脚本目录
023 | URL = "https://storage.googleapis.com/tensorflow/tf-keras-datasets/mnist.npz" 024 | SHA256 = "731c5ac602752760c8e48fbffcf8c3b850d9dc2a2aedcf2cc48468fc17b673d1" 025 | BASE = Path(__file__).resolve().parent 026 | 027 |
左侧看代码,右侧逐行讲解。
这三行给后续调用提供固定值。全大写是命名惯例。
- 第23行将 MNIST 归档地址存进
URL。第42行把它传给urlopen时才联网。 - 第24行将期望的 SHA-256 摘要存为 64 个十六进制字符:
731c5ac602752760c8e48fbffcf8c3b850d9dc2a2aedcf2cc48468fc17b673d1。第44、47行把实际文件的摘要与它比较。 - 第25行逐步找到脚本目录:
__file__给出脚本位置,Path(__file__)将其变成路径对象,.resolve()得到绝对路径,.parent去掉最后的文件名。
假设脚本在 D:/example/prepare_mnist.py,BASE 就是 D:/example。第71、72行据此得到默认输入 D:/example/mnist.npz、默认输出 D:/example/mnist_readable。显式填写 --output mnist_preview 时,这类相对路径用终端当前目录解析,具体见第7节。
第28–35行:分块计算SHA-256,每一步是什么
028 | def sha256(path):
029 | digest = hashlib.sha256()
030 | with path.open("rb") as source:
031 | for block in iter(lambda: source.read(1024 * 1024), b""):
032 | digest.update(block)
033 | return digest.hexdigest()
034 |
035 | 左侧看代码,右侧逐行讲解。
sha256(path) 接收文件路径,返回该文件的十六进制摘要。每次读一块,所有字节按原顺序进入同一个摘要计算。
- 第28–29行定义函数,创建一个空的摘要累积器
digest = hashlib.sha256()。 - 第30行以
"rb"打开文件,读到的是字节。with负责离开代码块时关闭文件。 - 第31–32行把
lambda理解为每次「读下一块」的操作。iter(这个操作, b"")反复读,直到结果等于空字节串。每次读到的非空块交给digest.update(block)。 - 第33行用
hexdigest()返回最终摘要字符串。摘要对象在with块外仍可访问,文件此时已关闭。
以一个恰好 1 MiB 加 3 字节的文件为例。第一次 read(1024 * 1024) 返回 1,048,576 字节并更新摘要;第二次只返回剩余 3 字节,也更新摘要;第三次返回 b"",循环结束,最后取总摘要。分块和一次把所有字节读入得出的摘要一致,分块所需的临时内存较少。
第36–51行:先用临时文件下载,再校验归档
036 | def get_archive(path):
037 | if not path.exists():
038 | path.parent.mkdir(parents=True, exist_ok=True)
039 | temporary = path.with_suffix(".npz.part")
040 | print("Downloading the archive used by the official Keras loader...", flush=True)
041 | print(URL, flush=True)
042 | with urlopen(URL, timeout=120) as response, temporary.open("wb") as destination:
043 | shutil.copyfileobj(response, destination)
044 | if sha256(temporary) != SHA256:
045 | raise ValueError("Download checksum mismatch. Please download again.")
046 | temporary.replace(path)
047 | if sha256(path) != SHA256:
048 | raise ValueError("This archive does not match the checksum in the Keras source.")
049 | print("SHA-256 verification passed.", flush=True)
050 |
051 | 左侧看代码,右侧逐行讲解。
get_archive(path) 在正式归档缺失时下载,在正式归档存在时直接校验。先看第37行和第47行的缩进:第38–46行只属于「文件缺失」分支,第47–49行两种情况都会执行。
| 归档初始状态 | 经过的行 | 结果 |
|---|---|---|
已有 mnist.npz 且摘要一致 |
37 → 47 → 49 | 直接打印校验通过 |
已有 mnist.npz 且摘要不一致 |
37 → 47 → 48 | 抛出 ValueError,结束流程 |
缺少 mnist.npz,下载且校验成功 |
37 → 38–46 → 47 → 49 | 先生成临时文件,验证后成为正式归档 |
下载分支按顺序执行:第38行补建父目录;第39行用 with_suffix(".npz.part") 把 mnist.npz 变成临时路径 mnist.npz.part;第40–41行用 flush=True 及时显示下载信息。第42行打开网络响应和临时文件,其中 timeout=120 是网络操作的超时设置;第43行 copyfileobj 把字节写入以 "wb" 打开的文件。with 结束后关闭两个流,此时磁盘上仍是临时文件。
第44–45行摘要不符就抛异常;通过后第46行用 replace 改为正式路径。下载中断可能留下 .npz.part,未走到第46行便不会出现新正式归档。
第52–68行:一张张保存PNG,同时写标签表
052 | def export_split(images, labels, split, output, limit):
053 | folder = output / split
054 | image_folder = folder / "images"
055 | image_folder.mkdir(parents=True)
056 | count = len(images) if limit is None else min(limit, len(images))
057 | with (folder / "labels.csv").open("w", newline="", encoding="utf-8-sig") as file:
058 | writer = csv.writer(file)
059 | writer.writerow(["filename", "label"])
060 | for index in range(count):
061 | filename = f"image_{index:05d}.png"
062 | # uint8 (28, 28) arrays become grayscale PNGs, with unchanged pixels.
063 | Image.fromarray(images[index]).save(image_folder / filename)
064 | writer.writerow([filename, int(labels[index])])
065 | if (index + 1) % 5000 == 0 or index + 1 == count:
066 | print(f"{split}: {index + 1:,} / {count:,} images exported", flush=True)
067 |
068 | 左侧看代码,右侧逐行讲解。
export_split(images, labels, split, output, limit) 将一套数组导出为图片和标签表。以 split="train"、output=mnist_preview、limit=20 为例说明。
- 第52–55行分别拼出
mnist_preview/train与其中的images,并创建目录。parents=True补建缺失的父目录。由于未给exist_ok=True,图片目录已经存在时会报错。 - 第56行不限制时取
len(images),给了 limit 时取两者中较小值。本例图像共 60000 张,count=min(20,60000)=20。 - 第57–59行以写入模式打开
train/labels.csv,用newline=""让 CSV 写入器控制行尾,用utf-8-sig保存字符编码,随后写下表头filename,label。 - 第60–64行
range(count)给出 0 至 19。{index:05d}用 0 补到至少五位;Image.fromarray(images[index]).save(...)按原像素写 PNG;再用相同索引取int(labels[index]),写文件名与标签。 - 第65–66行用
index+1算已完成张数,每满 5000 张或完成最后一张就报告进度。本例index=19时打印train: 20 / 20 images exported;较大的数字用逗号分隔千位。
用本地归档的前三条训练记录核对。由索引 0 读出的第一张是数字 5,下一轮同时读索引 1 的图片与标签,防止拿错对应关系。
| index | 读取的像素数组 | 写入 train/labels.csv 的一行 |
|---|---|---|
| 0 | images[0] |
image_00000.png,5 |
| 1 | images[1] |
image_00001.png,0 |
| 2 | images[2] |
image_00002.png,4 |
常规 PNG 大小为 28×28,像素值保持不变。标签表有一行表头和 20 行记录,limit 只约束这次循环。
第69–81行:解析命令行,并拒绝覆盖已有输出
069 | def main():
070 | parser = argparse.ArgumentParser(description=__doc__)
071 | parser.add_argument("--input", type=Path, default=BASE / "mnist.npz")
072 | parser.add_argument("--output", type=Path, default=BASE / "mnist_readable")
073 | parser.add_argument("--limit", type=int, default=None,
074 | help="Export only the first N images in EACH split; default: all.")
075 | args = parser.parse_args()
076 | if args.limit is not None and args.limit < 1:
077 | parser.error("--limit must be a positive integer.")
078 | output = args.output.resolve()
079 | if output.exists():
080 | raise FileExistsError(f"Output already exists: {output}\nUse --output with a new folder name.")
081 | 左侧看代码,右侧逐行讲解。
main() 先读取命令行,决定从哪读、写多少、写到哪。第70行的 description=__doc__ 把开头说明带进帮助文字。第71–74行先登记参数,第75行 parse_args() 再读本次命令。
| 属性 | 没写这个选项时 | 输入 --limit 20 --output mnist_preview 时 |
|---|---|---|
args.input |
BASE / "mnist.npz" |
同左 |
args.output |
BASE / "mnist_readable" |
路径 mnist_preview |
args.limit |
None,两个子集全部导出 |
整数 20,各子集取前 20 张 |
第76–77行先检查 args.limit is not None,再判断是不是小于 1。由于 and 从左向右算,省略 limit 时不会对 None 做数值比较;给了 0 或负数则由 parser.error 结束。
第78行调用 .resolve() 得到绝对输出路径。给相对路径时基于终端当前目录,默认路径则基于脚本所在目录。第79–80行发现目标路径已存在便报 FileExistsError。这发生在第82行读取归档之前,所以重复运行同一输出目录时,会停在路径检查。
第82–86行:取得归档,再读取四个数组
082 | get_archive(args.input) 083 | with np.load(args.input, allow_pickle=False) as archive: 084 | x_train, y_train = archive["x_train"], archive["y_train"] 085 | x_test, y_test = archive["x_test"], archive["y_test"] 086 |
左侧看代码,右侧逐行讲解。
第82行先调用 get_archive(args.input),校验完成才进入第83行。np.load(..., allow_pickle=False) 打开归档,并禁用通过 pickle 加载对象数组;with 结束后关闭归档资源。第84–85行以归档里的键名取出四个数组,分别留在内存中的变量里:
| 归档键与接收变量 | 用途 | 索引 0 的类型和内容 |
|---|---|---|
x_train |
训练图片 | 28×28 像素矩阵,对应一张 5 |
y_train |
训练标签 | 整数 5 |
x_test |
测试图片 | 28×28 像素矩阵,对应一张 7 |
y_test |
测试标签 | 整数 7 |
赋值 x_train, y_train = archive["x_train"], archive["y_train"] 可顺序读:右边先按两个键各取一个数组,左边名字再一一接收。图片和标签用同一索引配对。训练集和测试集都从各自的索引 0 开始。
第87–95行:验证形状、类型,并打印基本信息
087 | expected = [(x_train, (60000, 28, 28)), (y_train, (60000,)),
088 | (x_test, (10000, 28, 28)), (y_test, (10000,))]
089 | for array, shape in expected:
090 | if array.shape != shape or array.dtype != np.uint8:
091 | raise ValueError("Unexpected MNIST array shape or data type.")
092 | print("Training images:", x_train.shape, "Labels:", y_train.shape)
093 | print("Test images: ", x_test.shape, "Labels:", y_test.shape)
094 | print("First training image label:", int(y_train[0]))
095 | 左侧看代码,右侧逐行讲解。
第87–88行用 expected 把每个数组与它应有的形状写在一对括号里。第89行循环逐对拆开,array 是当前数组,shape 是它的预期形状。
| 数组 | 预期形状 | 每个轴表示什么 |
|---|---|---|
x_train |
(60000, 28, 28) |
训练张数、高、宽 |
y_train |
(60000,) |
每张训练图一个标签 |
x_test |
(10000, 28, 28) |
测试张数、高、宽 |
y_test |
(10000,) |
每张测试图一个标签 |
(60000,) 的尾逗号表示单元素元组;(60000) 仍是整数。第90–91行分别检查形状与 dtype。若误把图像转成 float32,即使形状完全相符,array.shape != shape 为假、array.dtype != np.uint8 为真,假 or 真 仍然触发 ValueError。uint8 每个元素占 1 字节,所以 60000×28×28=47,040,000 个训练像素约占 47 MB。
通过以后,第92–93行输出形状,第94行打印 int(y_train[0])。本地归档给出的第一条标签为 5,这里只是从数组读标签。
第96–104行:导出两个子集,再做第一张图预览
096 | export_split(x_train, y_train, "train", output, args.limit) 097 | export_split(x_test, y_test, "test", output, args.limit) 098 | 099 | # These two extra files make the first image easy to inspect. 100 | Image.fromarray(x_train[0]).resize( 101 | (280, 280), Image.Resampling.NEAREST 102 | ).save(output / "first_train_large.png") 103 | np.savetxt(output / "first_train_pixels.csv", x_train[0], fmt="%d", delimiter=",") 104 |
左侧看代码,右侧逐行讲解。
第96、97行用同一个 export_split 分别处理训练和测试数组。以 --limit 20 为例,根目录里会出现:
mnist_preview/
train/images/ 20 张 28×28 灰度 PNG
train/labels.csv 从 image_00000.png,5 开始
test/images/ 20 张 28×28 灰度 PNG
test/labels.csv 从 image_00000.png,7 开始
first_train_large.png 第一张训练图,280×280
first_train_pixels.csv 第一张训练图,28 行×28 列
第100–102行从 x_train[0] 创建图像,再用最近邻算法放大,最后保存。宽高各变成 10 倍,所以原图上每个像素显示成 10×10 的同值方块。以本地归档为例,第一张的 x_train[0,6,10] 为 94,放大图中第 60–69 行、第 100–109 列的整块也是 94。括号里的三行是一条链式调用。
第103行将同一张原始二维数组写成 CSV,fmt="%d" 指每个值以整数输出,delimiter="," 指列之间用逗号。数组下标从 0 开始,所以 94 对应像素表的第 7 行、第 11 列。常规导出的 28×28 图用于模型输入,放大图用于看细节。
第105–119行:写入数据来源说明
105 | (output / "DATA_SOURCE.txt").write_text(
106 | "MNIST handwritten digit dataset\n"
107 | "Copyright: Yann LeCun and Corinna Cortes, per Keras documentation.\n"
108 | "License: https://creativecommons.org/licenses/by-sa/3.0/\n"
109 | "Documentation: https://keras.io/api/datasets/mnist/\n"
110 | "Loader: https://github.com/keras-team/keras/blob/master/keras/src/datasets/mnist.py\n"
111 | f"Archive: {URL}\nSHA-256: {SHA256}\n"
112 | "Export: original 28x28 grayscale pixels preserved as PNG.\n"
113 | "first_train_large.png is enlarged only for viewing, not for model input.\n"
114 | "The published MNIST test set and its labels are public.\n"
115 | f"Export limit per split: {args.limit if args.limit is not None else 'all'}\n",
116 | encoding="utf-8",
117 | )
118 | print("\nFinished. Open this folder:", output)
119 | 左侧看代码,右侧逐行讲解。
第105–117行向 DATA_SOURCE.txt 写入一份数据说明。路径由 output / "DATA_SOURCE.txt" 得到。第106–115行括号内相邻的字符串会拼成一段文字,每个 \n 另起一行,末尾的 encoding="utf-8" 指定写入编码。
- 第106–110行写数据集名称、代码记录的版权与许可证,以及文档和加载器地址。
- 第111行用 f 字符串把常量
URL和SHA256填到Archive和SHA-256两行。 - 第112–114行说明普通 PNG 保留原始 28×28 像素,放大版供预览,公开测试集有标签。
- 第115行如果
args.limit有值就插入该值,否则插入all。给--limit 20时写Export limit per split: 20;实际张数仍由第56行对每个子集取较小值来决定。 - 第118行在文件写完后打印
Finished. Open this folder:以及绝对输出路径。
第120–122行:入口开关,以及整份流程怎样串起来
第121–122行决定何时调用 main()。__name__ 是 Python 给当前模块的名字,== 在这里比较字符串。
| 使用方式 | 本文件中的 __name__ |
会调用 main() 吗 |
|---|---|---|
python prepare_mnist.py --limit 20 --output mnist_preview |
__main__ |
会 |
import prepare_mnist |
prepare_mnist |
不会,可显式调用其中的函数 |
启动主程序后,执行依次经过第75行读参数,第78–80行检查输出位置,第82–85行取得归档和数组,第87–94行校验尺寸及类型,第96–97行调用两次导出函数,第100–103行写预览图片和像素表,最后第105–118行保存来源说明并提示完成。Python 读到 def 时只建立函数;例如 export_split 要等第96行传入训练数据才开始保存图片。