astropy.io.fits 演进史：PyFITS 并入 Astropy 前的版本历程与技术沉淀

• 科学计算
• 科研
• 数据分析

astropy.io.fits是 Astropy 中负责读写 FITS（Flexible Image Transport System）文件的核心子包，其前身是独立发布的 PyFITS 库。本指南以 history.rst 这份官方历史文档为骨架，系统梳理 PyFITS 从 0.6.2 到 3.4.0 的完整版本脉络，提炼其在 Header 接口、表读写、图像压缩、校验机制、内存映射等方向上的技术演进，并结合当前仓库源码说明这些能力在今天astropy.io.fits中的具体落点。读完本文，你将理解 FITS 生态中许多关键 API 与配置项为何长成现在这个样子，也能为迁移旧 PyFITS 代码提供直接依据。

一、背景：PyFITS 与 astropy.io.fits 的渊源

在并入 Astropy 之前，astropy.io.fits是一个名为PyFITS的独立包。PyFITS 不再单独维护，其后续开发全部并入 Astropy，本文档记录的正是 PyFITS 在合并之前的全部发布历史。3.4.0（2016-01-29）是 PyFITS 作为独立包的最后一个版本，此后该功能以astropy.io.fits的形式在 Astropy 仓库中持续演进。

从时间线上看，PyFITS 的版本跨度长达十余年：早期（0.6.x ~ 0.9.x）绑定 numarray 与 Python 2，1.x 时代转向 numpy，2.x 时代补全压缩、校验和、uint 等 FITS 生态关键能力，3.x 时代完成了 Header 接口重写、内存映射默认开启、验证选项细化等现代化改造。今天astropy.io.fits的大多数行为约定，都能在这份历史中找到源头。

二、版本时间线：从 0.6.2 到 3.4.0 的关键里程碑

从源码结构看，这些里程碑的痕迹至今仍保留在 astropy/io/fits 包中：card.py、header.py、column.py、fitsrec.py、convenience.py、verify.py、diff.py、hdu/（含compressed、groups等子模块）分别对应历史上各阶段沉淀下来的实现。

三、主题演进深挖

3.1 Header 接口的彻底重写（3.1 里程碑）

PyFITS 3.1 对Header类做了一次近乎完全的重写，核心目标是把原先埋在CardList里的操作能力全部收归Header本身，并让Header成为一个可像 dict/OrderedDict 一样使用的有序映射。这次重写确立的接口约定，正是今天astropy.io.fits的 Header 行为：

• 完整实现 dict 接口：header['NAXIS'] = 2即可新增或更新关键字（旧接口中必须用Header.update）。
• 值与注释同时赋值：header['NAXIS'] = (2, 'Number of axes')。
• 指定插入位置：header.set('NAXIS', 2, 'Number of axes', after='BITPIX')，Header.set取代旧的Header.update用法；Header.insert()还支持以关键字名定位插入点及after参数（3.2.1 补齐）。
• 直接访问卡对象：Header.cards取代Header.ascardlist()/Header.ascard；Card对象可与(keyword, value, comment)元组互换使用。
• 注释访问：header.comments['NAXIS']可查看与修改注释。
• 重复关键字：允许('HISTORY', 0)形式的(keyword, index)元组访问与删除重复卡；普通关键字查找恒返回第一个副本，而 COMMENT/HISTORY 等注解性关键字返回有序序列。
• 通配符与切片：header['NAXIS*']与切片均返回一个新的Header（旧版返回CardList）。
• 比较与拼接：两个 Header 可做严格相等比较，可用+运算符拼接（等价于Header.extend）。

新版接口的诸多细节可以对照 header_transition.rst 这篇随 PyFITS 3.1 发布、至今仍收录在仓库中的过渡指南，以及当前 header.py 中set、insert、rename_keyword、fromtextfile/totextfile、通配符匹配_wildcardmatch等方法的实现。

3.2 校验（Verification）选项的演化

PyFITS 3.3.0 为可修复错误与不可修复错误的处理引入了更细粒度的报告控制，新增了六种组合选项：

• fix+ignore、fix+warn、fix+exception
• silentfix+ignore、silentfix+warn、silentfix+exception

这些选项至今仍定义在 verify.py 的VERIFY_OPTIONS列表中，语义在_Verify.run_option与verify中实现：fix/silentfix决定是否执行修复，+ignore/+warn/+exception决定不可修复错误的报告方式；单独的fix/silentfix保持旧默认行为（对不可修复错误抛VerifyError）。output_verify参数在 hdulist.py 的fitsopen签名中接受"fix"、"silentfix"、"ignore"、"warn"、"exception"及上述任意组合。

与之相关的默认行为变化同样值得注意：PyFITS 0.9 确立了"输入宽松、输出严格"的默认策略；3.0.4 起写文件默认以fix模式验证输出（自动修正常见格式错误而非抛异常）。另外，3.1 起pyfits.open()的checksum参数接受'remove'值，用于忽略并移除文件中的 CHECKSUM/DATASUM；2.2/2.4 逐步让校验和读写符合 FITS 标准，并配套了fitscheck命令行工具。

3.3 表（Table）读写能力的演进

表处理是 PyFITS 迭代最密集的领域之一，能力逐步累积为今天的完整形态：

• 建表 API：pyfits.new_table在 3.2 被标记 pending deprecation，3.3 完全废弃，官方推荐改用BinTableHDU.from_columns（二进制表）与TableHDU.from_columns（ASCII 表）；FITS_rec.from_columns（见 fitsrec.py）则用于直接构造 FITS 兼容的 recarray。
• 列格式：支持 Q 格式（64 位描述符的变长数组，单表可变长数据可超 4 GB）、P 格式（变长数组）、TDIMn 多维列（3.0）、X 格式位标志列（0.9.3，用户侧以布尔数组呈现）、零宽字段（3.0）、complex 列（0.8）；Column与ColDefs自 3.2 起新增.dtype属性直接给出 numpy dtype。
• 数据访问：2.3 起FITS_rec['columnName']与table.field('columnName')等价并返回 ndarray；FITS_record（行对象）支持完整切片、元组/列表赋值；变长数组列可由 list 构造；Column数组支持广播赋值（3.2.1 修复）。
• ASCII 表：0.9.6 支持写 ASCII 表扩展；字符串填充区分二进制表（0 字节）与 ASCII 表（空格）的差异在 3.0 修复；缺省字符串列值由'0.0'改为空字符串（3.2）。
• dump/load：pyfits.tdump/tcreate与BinTableHDU.tdump/tcreate分别更名为pyfits.tabledump/tableload与BinTableHDU.dump/load（3.1），新格式为每个值加引号，兼容旧 dump 但解析更健壮；这些函数在 convenience.py 中仍可找到（tabledump、tableload）。
• 数据完整性修复：3.1.2/3.1.3 修复变长数组列 TFORMn 关键字漏写最大数组长度参数的问题；堆（heap）大小计算错误导致写坏文件的问题在 3.2.1 修复；布尔字段建表全变False、整型数组错配浮点列等边界问题在 3.1.2 修复。

3.4 图像压缩：从瓦片压缩到量化抖动

压缩能力是这条历史线中最具技术含量的部分：

• 2.0 初步支持：引入 Tiled Image Compression 约定，将 n 维图像划分为矩形瓦片，每片作为连续数据块压缩后存入二进制表的变长数组列；支持 GZIP、RICE、H-Compress、IRAF 像素列表（PLIO）四种算法；CompImageHDU的构造函数签名包含compressionType（默认'RICE_1'）、tileSize（默认每行一片）、hcompScale、hcompSmooth、quantizeLevel；压缩图像 HDU 在用户侧表现得与普通图像 HDU 一致。
• 3.2 重写后端：改为使用标准 CFITSIO（随包内置 v3.35，支持 Tiled Image Convention v2.3），系统打包者可改用系统版 CFITSIO（低于 3.28 未测试）；新增 ZQUANTIZ 与 ZDITHER0 关键字支持——quantize_method可设为SUBTRACTIVE_DITHER_1/SUBTRACTIVE_DITHER_2，dither_seed支持手动指定、系统时钟或基于校验和的自动生成；GZIP 可无损压缩；瓦片压缩图像可通过 Q 格式突破 4 GB 上限。
• 校验和分工：压缩图像 HDU 中ZHECKSUM/ZDATASUM覆盖原始图像 HDU，CHECKSUM/DATASUM覆盖压缩图像 HDU（3.2.1 修复）。
• 今日实现：当前 compressed.py 中CompImageHDU.__init__的参数（compression_type、quantize_level、quantize_method、dither_seed、do_not_scale_image_data、uint、scale_back）正是上述历史的直接延续；_quantization.py 中的DITHER_METHODS映射（NO_DITHER、SUBTRACTIVE_DITHER_1、SUBTRACTIVE_DITHER_2）与文档描述一一对应。

3.5 内存映射与文件 I/O 的演进

• memmap 默认开启：3.1 起pyfits.open()默认memmap=True，并提供全局开关pyfits.USE_MEMMAP与环境变量PYFITS_USE_MEMMAP控制默认行为；这一开关如今沉淀为init.py 中Conf.use_memmap配置项。
• 模式语义：3.0.5 明确readonly在 memmap 下等价于copyonwrite（内存中可改、不落盘），并新增denywrite模式用于拒绝任何数据修改。
• 文件对象支持：1.4 起所有便利函数与类方法既接受文件名也接受文件对象（StringIO、GzipFile 等）；3.0.4 起 gzip/zip 压缩的 FITS 文件可无视扩展名被自动识别打开；1.1 的 StreamingHDU 允许不将整幅图像载入内存而流式写入扩展；3.0.6 修正ostream模式以'wb'打开底层文件。
• 今日参数：fitsopen中的memmap、lazy_load_hdus（1.3 加入的惰性 HDU 加载）、cache、decompress_in_memory（6.0 加入）等参数共同定义了今天的文件打开行为，详见 hdulist.py 的fitsopen签名。

3.6 伪无符号整数与图像数据缩放

FITS 标准用BZERO/BSCALE表示伪无符号整数：例如int16数据配BZERO=32768、BSCALE=1即代表uint16。PyFITS 2.0 支持uint16选项，2.3 扩展为 uint8/16/32/64 全套；3.2 起uint=True成为打开文件的默认参数之一。相关配套能力包括：

• do_not_scale_image_data=True：读取时不自动应用 BSCALE/BZERO（2.4 加入），适合仅想改头部信息、避免数据被重写成浮点的场景；
• scale_back=True：保存时按原始 BITPIX 与 BSCALE/BZERO 还原数据（3.1 加入，等价于在 flush 前调用hdu.scale(type, 'old')）；
• save_backup=True：update/append 模式下在 flush 前自动备份原始文件（3.1 加入，备份名依次为.bak、.bak.1…）；
• ImageHDU.scale()方法支持option='old'（恢复原 BSCALE/BZERO）与option='minmax'（按数据范围适配整型）等缩放方案，其option='old'在 3.1 曾一度失效并被修复。

3.7 便利函数（convenience functions）的沉淀

模块级便利函数自 1.0 起成为 PyFITS 的标志性 API，今天全部保留在 convenience.py 中：getheader、getdata、getval、writeto、append、update、info，以及 2.0 新增的setval、delval。2.4 还加入了 HDU 级方法update_ext_name/update_ext_version（更新 EXTNAME/EXTVER）、filebytes（计算该 HDU 写入文件所占字节数）、HDUList.fileinfo()（返回 HDU 在文件中的头/数据位置字典）与HDUList.filename()（2.3）。2.4 的append还新增verify=False参数，跳过对既有文件的校验以大幅加快向大文件追加的速度。

3.8 头关键字能力：HIERARCH、RVKC 与通配符匹配

• HIERARCH 约定：1.0 加入；2.4 将 HIERARCH 卡关键字加值总长度上限由 68 放宽到 69 字符；3.1.2 修复 HIERARCH 解析中缺空格、前导空格、小写关键字被误判为非法等问题。
• Record-valued 关键字卡（RVKC）：1.4 依据 FITS WCS 畸变论文引入。其语法为keyword= 'field-specifier: float'，field-specifier 由field与field.index构成，可多层嵌套（如DP1.AUX.1.COEFF.0）；关键字不区分大小写而 field-specifier 区分。文档给出了完整示例与三种访问方式：按卡索引（返回整串字符串）、按纯关键字（返回该关键字最低索引卡的整串值）、按keyword.field（返回浮点值），并支持*（任意零或多个字符）、?（单字符）、...（跨层级匹配，仅可置于末尾）三种模式匹配键。旧版以CardList承载匹配结果，3.1 后废弃CardList；今天的enable_record_valued_keyword_cards配置项（init.py 中的Conf）控制该特性开关。
• 通配符扩展：3.3 起header['DATE*']可匹配关键字中的连字符及任意字符，而不再局限于[0-9A-Za-z_]，以兼容 HIERARCH 与 RVKC 中更宽泛的合法字符集合。
• CONTINUE 卡：0.9 支持读写；3.1.2 修复 Python 2 下从字节串/Unicode 字符串创建 CONTINUE 卡的不一致；长注解卡（HISTORY/COMMENT）不再拆入 CONTINUE 卡而是拆成多条注解卡（3.0.4 修复）。当前 card.py 中的Card.fromstring、Card.normalize_keyword、Card.is_blank（3.3 新增，判断完全空白卡）等成员正是这些能力的延续。

3.9 关键行为变化与代表性修复

• 废弃警告策略：3.3 起废弃 API 警告默认总是显示（与 Astropy 同步），脚本中可用pyfits.ignore_deprecation_warnings()关闭；0.8/1.0 时代建议以python -Wd运行以查看被忽略的 DeprecationWarning。
• Header 值合法性：3.1.3 起禁止将 NaN/Inf 浮点值写入头（FITS 标准未定义其表示）；布尔值与数值的替换在 3.2.1 修复（True可替换为整数 1，数值类型可上下转型，如'0'换为'0.0'）。
• 空白处理：3.1 起头部字符串值按 FITS 标准自动去除尾随空格，全局配置fits.STRIP_HEADER_WHITESPACE可关闭该行为（对应今天的Conf.strip_header_whitespace）；为兼容 IRAFWATj_nnn约定，需要逐字保留空白时可临时关闭。
• 扩展名大小写：2.1 提供setExtensionNameCaseSensitive，3.1 以全局变量pyfits.EXTENSION_NAME_CASE_SENSITIVE取代，对应今天的Conf.extension_name_case_sensitive；2.4 起 EXTNAME/EXTVER 允许出现在 PRIMARY HDU 中并反映到.name属性与pyfits.info()。
• 非标准文件：2.1 支持SIMPLE=F文件（读作_NonstandardHDU）与未知 XTENSION 值扩展（_NonstandardExtHDU）；2.2 提供ignore_missing_end=True以容忍缺失 END 卡的坏文件；3.0.2 起零基索引（C/Python 惯例）在文档与警告中明确说明，以区别于 FORTRAN 惯例。
• FitsHDU：3.1 支持将整个 FITS 文件嵌入另一文件数据区，FitsHDU.fromhdulist()生成嵌入 HDUList 的新 FitsHDU；配套的HDUList.fromstring可从内存中的字节缓冲解析出完整 HDUList（3.1，修复自 3.0 起_BaseHDU.fromstring的缺陷）。
• 平台与稳定性：多年间修复了大量 OSX 大文件截断（>2^32 字节）、Windows mmap 崩溃、GNU Hurd 无 mmap flush、Solaris GZIP 压缩总线错误、内存泄漏与并发写文件竞态（mktemp）等问题；3.2 重排了 OS 文件模式与 PyFITS 内部模式的映射，使已打开的类文件对象只需具备相应读写能力即可使用。
• 工具链：3.1 新增pyfits.diff模块（FITSDiff、HeaderDiff等）与fitsdiff程序；3.1.2 起通过 console_scripts 入口点安装fitsdiff/fitscheck，改善 Windows 支持。

3.10 PyFITS 3.3 移除与废弃的 API 清单

3.3.0 声明这是最后一个支持以下自 v3.1 起标记废弃的 API 的版本（3.3.x 补丁版仍保留），对迁移旧代码具有直接的清单价值：

此外，3.2 移除了createCard、createCardFromString、upperKey、ColDefs.data、setExtensionNameCaseSensitive、_File.getfile、_TableBaseHDU.get_coldefs、Header.has_key、Header.ascardlist等旧接口，并将CompDataHDU的updateHeader系列方法、compData属性及 HDU 内部属性_hdrLoc/_datLoc/_datSpan（更名_header_offset/_data_offset/_data_size）标记为 pending deprecation。Card的is_blank属性则于 3.3 新增，用于判断完全空白的卡。

四、面向迁移者的实用建议

如果你手头还有以pyfits命名的旧代码，官方历史文档给出的迁移路径可以总结为：

1. 先摸清废弃面：以python -Wd运行脚本，让所有 DeprecationWarning 显式输出，逐一对照上文 API 清单替换。
2. Header 操作：把Header.has_key(k)换成k in header；把Header.update(keyword, value, comment)换成Header.set或直接下标赋值header['NAXIS'] = (2, 'Number of axes')；把header.ascard/ascardlist()换成header.cards。
3. 删除语义：旧版del header[keyword]对不存在的关键字静默无操作，新接口会告警且未来会抛KeyError，建议先if keyword in header:判断或用try/except KeyError包裹。
4. 表建表：把pyfits.new_table(coldefs, nrows=N)改为BinTableHDU.from_columns(coldefs, nrows=N)（二进制表）或TableHDU.from_columns(...)（ASCII 表），两者参数兼容。
5. 展示行为：交互环境中直接输入header（repr）即按 FITS 文件格式逐卡换行显示；print(header)（str）返回的是无换行的文件字面量。

详细对照可查阅仓库中的 header_transition.rst。

五、从历史看今日：能力落点速查

将历史功能映射到当前astropy.io.fits的源码位置，便于进一步深入：

• 全局配置：Conf类（init.py）集中了enable_record_valued_keyword_cards、extension_name_case_sensitive、strip_header_whitespace、use_memmap、lazy_load_hdus、enable_uint六个配置项——它们分别对应历史上 RVKC、EXTNAME 大小写、头空白处理、内存映射、惰性加载与伪无符号整数的反复打磨。
• 打开文件：fitsopen（hdulist.py）的mode、memmap、save_backup、uint、checksum、disable_image_compression、do_not_scale_image_data、scale_back、output_verify、ignore_missing_end、lazy_load_hdus、use_fsspec、decompress_in_memory等参数几乎完整承载了 2.x~6.x 的功能演进。
• 验证机制：VERIFY_OPTIONS与_Verify（verify.py）实现全部验证选项的解析与报告语义。
• 压缩与量化：CompImageHDU（compressed.py）与DITHER_METHODS、Quantize（_quantization.py）。
• 表数据：FITS_rec/FITS_record与from_columns（fitsrec.py），配合Column/ColDefs（column.py）。
• 便利函数：getheader、getdata、getval、setval、delval、writeto、append、update、info、tabledump、tableload等（convenience.py）。
• Header 与 Card：header.py 与 card.py。

结语

PyFITS 十余年的版本历史，本质上是围绕 FITS 标准的一次次"对齐"与"补全"：从 numarray 时代的奠基，到 numpy 时代的重写，再到 3.x 时代对 Header 接口、验证语义、内存映射与瓦片压缩的现代化。这些决策至今仍以配置项、函数签名与类接口的形式活在astropy.io.fits中。对于希望在读写 FITS 文件时理解"为什么是这个行为"、以及需要从旧 PyFITS 代码迁移的开发者而言，history.rst 与 header_transition.rst 两份附录是最权威的第一手资料，配合上述源码路径即可完成从"历史约定"到"当前实现"的完整对照。

• 科学计算
• 科研
• 数据分析