VisiData Loader 开发指南：从 open_＜filetype＞ 到 Saver 的完整实战教程

• 数据分析
• CLI
• 数据可视化

本指南以 VisiData 官方 API 文档（docs/api/loaders.rst）为主体，系统讲解如何为一个数据源编写全新的加载器（Loader）：包括open_<filetype>入口样板、Sheet子类与rowtype/rowdef约定、iterload/reload的数据加载机制、列（Column）枚举、文件类型猜测（guess_<filetype>）、Saver（保存器）、visidata.Path抽象以及 URL Scheme 加载器。读完本文，你将具备从零实现一个"可读可写、异步、可取消、带进度"的完整 VisiData 加载器的能力，并理解其底层源码是如何支撑这些能力的。

认识 Loader：VisiData 生态的扩展入口

在 VisiData 中，"加载器"指任何能把一种数据源（文件、URL、数据库、二进制流……）变成一张可交互表格的代码。官方文档给出的创建流程只有四步，任何加载器都遵循同一套骨架：

1. 编写open_<filetype>样板函数；
2. 创建FooSheet子类，声明rowtype与rowdef；
3. 实现FooSheet的reload或iterload加载数据；
4. 枚举FooSheet.columns定义列。

从源码结构看，这个约定贯穿了整个项目：所有内置格式（CSV、JSON、Parquet、SQLite、HDF5……）都位于 visidata/loaders/ 目录，以open_<filetype>、guess_<filetype>、save_<filetype>的命名规约注册到vd全局对象上。理解了这个骨架，你既可以往核心仓库提交新加载器，也可以把它做成独立插件。

Step 1：open_<filetype>样板函数

任何文件类型foo（扩展名为.foo的文件）都由一个open_foo函数负责创建对应的 Sheet。官方文档给出的最小样板：

@VisiData.api def open_readme(vd, p): return ReadmeSheet(p.base_stem, source=p)

• @VisiData.api装饰器把函数注册为vd对象的方法，使其在全局可用；
• 函数名中的<filetype>决定了文件类型：open_readme对应.readme扩展名，也可以在命令行用--filetype=readme或-f readme显式指定；
• 参数p是一个 visidata.Path 对象，代表被打开的文件（也可能是不存在的文件——例如用于创建新文件）；
• 真正的加载逻辑并不在这个函数里，而在它返回的 Sheet 中。你可以复用现有 Sheet 类型，也可以创建全新的类型；
• p.base_stem用于给 Sheet 命名，source=p把路径作为数据源传给 Sheet。

从源码看，open_<filetype>的实际调用点位于 visidata/_open.py 的openPath()（visidata/_open.py#L98-L170）：它按"URL scheme → 扩展名 → 内容猜测"的优先级查找open_<filetype>，找不到时最终回退到open_txt（visidata/_open.py#L205-L213，它会先探测第一行是否为 TSV）。也就是说，只要注册了open_<filetype>，VisiData 的打开流程会自动找到它。

Step 2：创建 Sheet 子类

加载器返回的 Sheet 需要声明两样东西：rowtype和rowdef。

class ReadmeSheet(TableSheet): rowtype = 'lines' # rowdef: [str]

• TableSheet（别名Sheet，见 visidata/sheets.py#L149 与 visidata/sheets.py#L1092）是最基本的"行 × 列"表格 Sheet，绝大多数加载器继承它。如果与其他加载器共享逻辑，可以继承更专门的 Sheet；如果数据不是表格（比如Canvas），则继承BaseSheet。
• rowtype只用于显示在状态栏右侧（参考 docs/api/interface.rst），应当用复数形式。不写时默认为"rows"。它给用户一个关于当前表格行类型的潜意识提示。
• rowdef只是一个注释，但对所有加载器都应给出：它声明了本 Sheet 每行数据的 Python 结构预期。几乎所有其他组件（列定义、表达式、选择/编辑操作）都依赖这个结构约定，因此写清楚它对后续维护者至关重要。

官方文档特别强调了一个易错点：str本身不能作为 rowdef。原因有二：

1. 每一行必须拥有唯一的rowid，默认取 Python 的id(row)。Python 会驻留（intern）常见字符串，值相同的字符串会共享同一个id，这会破坏行选择等依赖唯一 rowid 的功能；
2. str是不可变类型，无法在表格中就地修改。

所以行必须被包裹进 Pythonlist——它保证唯一、且可变。这就是rowdef: [str]的含义：每一行是"一个元素的列表"。

Step 3：把数据装进 rows

默认机制：reload()+iterload()

reload()在 Sheet 首次被推入界面时调用，之后用户按Ctrl+R也会触发。默认的TableSheet.reload()会遍历TableSheet.iterload()返回的行，并代为处理一些公共任务（比如以异步线程运行、把rows成员重置为新列表）。

因此，表格型加载器通常只需重写iterload()，用self.source逐行产出数据：

class ReadmeSheet(TableSheet): rowtype = 'lines' # rowdef: [str] def iterload(self): for line in self.source: yield [line]

• sheet.source就是open_readme里通过source=关键字传入的那个visidata.Path。注意：任何传给 Sheet 构造器的 kwarg 都会以同名属性保存在 Sheet 上——这是所有加载器传递配置的通用机制。
• visidata.Path是 Path-like 对象，但有一些额外特性，比如可迭代：for line in path会逐行产出文件内容。虽然也有visidata.Path.read_text()，但绝不要在加载器里写for line in p.read_text().splitlines()——那会把整个文件先读进内存才返回第一行。加载器必须能处理任意体量的数据（包括放不进内存的大文件），而Path.__iter__被优化为小批量读取（见 visidata/path.py#L170-L176），所以对基于行的文本格式，for line in path是可行的。

从源码看，默认加载链路是：TableSheet.reload()（带@asyncthread，见 visidata/sheets.py#L276-L290）→loader()→_iterloader()→ 你的iterload()，其中_iterloader()会把rows重置为空列表，并通过addRow()逐行加入（visidata/sheets.py#L313-L320）。内置的 CSV 加载器就是这条链路的典型实践：visidata/loaders/csv.py#L52-L81 中CsvSheet.iterload()用csv.reader逐行产出，遇到csv.Error时把异常对象本身作为行 yield，保证单个坏行不会中断整个加载。

第三方依赖的导入约定

如果加载器需要第三方库，必须在iterload()/reload()（必要时在open_<filetype>）内部导入，绝不能在模块顶层 import，否则库未安装时vd会直接启动失败。官方推荐的写法是：

modname = importExternal(modname, pythonPackageName)

importExternal（定义于 visidata/settings.py#L560-L567）在包缺失时会友好地输出package \modname` not installed; run: `pip install pythonPackageName`提示，而不是抛出堆栈。内置加载器大量使用这一模式，例如 [visidata/loaders/api_airtable.py#L19-L21](https://link.gitcode.com/i/adb34ecb5d3ebe35a02e954df09ae37d) 的open_airtable内部调用vd.importExternal('pyairtable')`。

默认列：先跑起来，再探索结构

默认情况下，一个 Sheet 只有一个 Column，直接显示行的字符串表示。所以上述示例已经是一个不错的起点：先用最省事的方式拿到行、拿一份样例数据启动vd，然后按Ctrl+Y探查生成的 Python 对象，找出应该显示在表格上的属性，再据此定义列。

更细粒度的控制：直接重写reload()

如果需要对整个加载过程做更多控制，可以绕过iterload()直接重写BaseSheet.reload()：

@asyncthread def reload(self): self.rows = [] for line in self.source: self.addRow([line])

这里有三个必须遵守的约定：

• @asyncthread让被装饰函数在独立线程中运行（详见 docs/api/async.rst）；
• sheet.rows必须重置为一个新列表，绝不要调用sheet.rows.clear()（因为加载期间可能有其他线程正在引用旧列表）；
• 始终通过addRow()添加行（定义见 visidata/sheets.py#L247-L251，它会处理 undo、行号等附带逻辑）。

异步加载的四个要点

在大数据集上于主线程加载会让界面卡死。好消息是：默认的TableSheet.reload+iterload结构天然就是异步的——行被一个一个yield，加载到哪一行哪一行就立即可用，且reload本身被@asyncthread装饰，在独立线程中执行。官方文档给出四条硬性经验：

1. 所有行迭代器都应包上Progress（定义见 visidata/threads.py#L111-L116），它会在每过一个元素时刷新进度百分比；
2. 不要依赖rows添加后的顺序，比如不要引用rows[-1]——异步加载期间行的顺序可能变化；
3. 捕获处理单行时可能抛出的任何Exception，并把异常对象本身作为该行加入。未捕获的异常会导致加载线程中止；
4. 不要使用裸except:子句，否则加载线程将无法用Ctrl+C取消。

进度与异常示例

class FooSheet(Sheet): ... def iterload(self): for bar in Progress(foolib.iterfoo(self.source.open_text())): try: r = foolib.parse(bar) except Exception as e: r = e yield r

注意Progress既可包裹可迭代对象（如上），也可作为上下文管理器使用，内部通过sheet.progresses维护进度显示（见 visidata/threads.py#L77-L109）。CSV 加载器对csv.Error的处理（visidata/loaders/csv.py#L72-L81）正是这一模式的真实应用。

加载器性能测试清单

写完后用一份非常大的数据集验证三点：

• 第一行是否立即出现；
• 进度百分比是否在持续更新；
• 能否用Ctrl+C取消加载。

仓库中 dev/checklists/manual-tests.md 和 dev/checklists/feature.md 也给出了更完整的验证流程参考。

Step 4：枚举 Columns

每个 Sheet 有一个columns属性，存放一组唯一的Column对象。每个Column提供从行中取值的不同视图：

class FooSheet(Sheet): rowtype = 'foobits' # rowdef: foolib.Bar object columns = [ ColumnAttr('name'), # foolib.Bar.name Column('bar', getter=lambda col,row: row.inside[2], setter=lambda col,row,val: row.set_bar(val)), Column('baz', type=int, getter=lambda col,row: row.inside[1]*100) ]

• 通常把columns定义为类成员（静态列列表）；如果列在数据加载前未知，可以在reload/iterload中用addColumn()动态添加（定义见 visidata/sheets.py#L577-L607）；
• 若rowdef是list且列是动态的，SequenceSheet.reload()可以代劳列的创建。SequenceSheet（visidata/sheets.py#L1095-L1102）专门面向"行是 Python 序列（list、namedtuple 等）"的 Sheet，按列序号自动生成ColumnItem。内置的 CsvSheet 就继承自它：

class FooSheet(SequenceSheet): rowtype = 'foobits' # rowdef: a list, which is a sequence of values def iterload(self): with foolib.iterfoo(self.source.open_text() as f: r = foolib.parse(bar) yield r

Column 的属性

除name外，以下属性都是构造器的可选参数：

Column基类定义于 visidata/column.py#L44-L52，其 getter/setter 通过getValue（visidata/column.py#L339）、getTypedValue（visidata/column.py#L314-L316）与getDisplayValue（visidata/column.py#L430-L433）构成完整取值链路。

getter 可以是任意函数，但很多加载器用一个静态的ItemColumn（针对 dict/list 行按 key/index 取值）和/或AttrColumn（针对行对象属性取值，见 visidata/column.py#L541-L551）列表就够用了。这取决于加载策略：有些加载器为了更快，宁可少做解析，相应地 Column 的 getter 就要更复杂一些。完整的 Column API 见 docs/api/columns.rst。

Passthrough options：透传底层库参数

凡是内部或外部 Python 库提供 kwargs 的加载器，官方鼓励用**options.getall("foo_")接口把同前缀的选项透传给库。getall(prefix)（见 visidata/settings.py#L279-L283）返回所有以prefix开头的选项字典（键名去掉前缀）。对csv这类把参数暴露给构造器的模块，做起来非常直接：

rdr = csv.reader(fp, **csvoptions())

内置的 CSV 加载器就是这么做的：先在模块级用vd.option('csv_delimiter', ...)等声明选项（visidata/loaders/csv.py#L8-L12），加载时csv_opts = self.source.options.getall('csv_')（visidata/loaders/csv.py#L60），保存时同理（visidata/loaders/csv.py#L90）。pandas 加载器也把pandas_<filetype>_前缀的选项透传给pd.read_*（见 visidata/loaders/_pandas.py#L163）。

完整示例：SAS7BDAT 加载器

这是一个可完全运行的sas7bdat（SAS 数据集文件）格式加载器，基于 Jared Hobbs 的sas7bdat库：

from visidata import Sheet, ItemColumn, Progress @VisiData.api def open_sas7bdat(vd, p): return SasSheet(p.base_stem, source=p) class SasSheet(Sheet): def iterload(self): import sas7bdat SASTypes = { 'string': str, 'number': float, } self.dat = sas7bdat.SAS7BDAT(str(self.source), skip_header=True, log_level=logging.CRITICAL) self.columns = [] for col in self.dat.columns: self.addColumn(ItemColumn(col.name.decode('utf-8'), col.col_id, type=SASTypes.get(col.type, anytype))) with self.dat as fp: yield from Progress(fp, total=self.dat.properties.row_count)

它浓缩了本文前面所有要点：@VisiData.api注册入口、延迟导入第三方库、在iterload中动态addColumn、用Progress包裹迭代、用total=指定已知总行数以便计算百分比。注意这里把columns赋值为新列表并逐个addColumn，而不是用类成员静态列——因为 SAS 的列只有打开文件后才知道。

猜测文件类型：guess_<filetype>

加载文件时，VisiData 会先看扩展名；扩展名不可靠或未知时，它会窥视文件开头内容，按结构猜测文件类型。vd.guess_<filetype>(path)就是干这个的：

• 若结构中不存在相应特征，函数应返回空（None）；
• 若存在，返回一个字典：
  • filetype：检测到的文件类型（对应vd.open_<filetype>）；
  • _likelihood（可选）：0–10 的数字，10 最可信，0 表示"没有别的能接盘时的最后手段"；
  • 其余任意键/值会被设置为open_<filetype>返回的 Sheet 上的选项。

从源码看，调度逻辑在 visidata/_open.py#L65-L85 的guessFiletype()：它遍历vd上所有guess_前缀函数，收集返回非空的候选，按_likelihood从大到小排序取第一名（缺省时按 1 计）。guess_extension（visidata/_open.py#L89-L94）把扩展名也作为一个_likelihood=3的候选参与竞争，意味着内容特征比扩展名更可信。猜中之后，其余键值会写入返回 Sheet 的 options（visidata/_open.py#L156-L160）。

示例：

@VisiData.api def guess_foo(vd, p): import foobar if p.open_text().read(8).startswith("#Foo"): enc = foobar.encoding(p) return dict(filetype='foo', foo_encoding=enc)

仓库中的真实案例极具参考价值：

• CSV 猜测：guess_csv（visidata/loaders/csv.py#L23-L42）用csv.Sniffer().sniff()分析首行，把嗅探出的方言参数（delimiter、quotechar 等）作为csv_前缀选项返回，并给filetype='csv'打上_likelihood=0——表示它是最后手段；
• ZIP/TAR 猜测：guess_zip/guess_tar（visidata/loaders/archive.py#L13-L23）用zipfile.is_zipfile()/tarfile.is_tarfile()探测，命中给_likelihood=10；
• git 仓库猜测：guess_git（visidata/apps/vgit/repos.py#L6-L8）检测目录内是否存在.git子目录；
• HTTP 内容类型：guess_http_content（visidata/loaders/http.py#L24-L25）根据响应的 Content-Type 子类型映射到对应 filetype。

Saver：让加载器"全双工"

一个完整的加载器还应该配套Saver。Saver 遍历所有rows与visibleCols，按保存格式的能力调用getValue、getDisplayValue或getTypedValue，把结果以该格式写入给定的 path。Saver 同样用@VisiData.api注册到vd对象作用域：

• p是要写入文件的visidata.Path；
• sheets是 1 个或多个待保存的 Sheet 列表。

Saver 应当保留列名，并把列的类型翻译成目标库的语义；Column 的其他属性一般不会保存。能处理类型化值的 Saver 应使用Column.getTypedValue；面向显示的 Saver（如 html、markdown、csv）应使用Column.getDisplayValue（它会考虑列的fmtstr）。

示例：基于 tabulate 的save_table

vd.option('tbl_tablefmt', 'simple', 'file format to save with "table" filetype') def get_rows(sheet, cols): for row in Progress(sheet.rows): yield [ col.getDisplayValue(row) for col in cols ] @VisiData.api def save_table(path, *sheets): import tabulate with path.open_text(mode='w') as fp: for vs in sheets: fp.write(tabulate.tabulate( get_rows(vs, vs.visibleCols), headers=[ col.name for col in vs.visibleCols ], **options.getall('tbl_')))

保存为table文件类型时，save_table会调用tabulate库，以tbl_tablefmt选项指定的文本格式输出。内置的多个 Saver 也用 tabulate，但它们略有不同——每个 tablefmt 都是一个独立的直接保存 filetype。

内置 Saver 的源码模式与本文完全一致：save_csv（visidata/loaders/csv.py#L85-L105）先写列名行，再用Progress包裹sheet.iterdispvals(format=True)逐行写出；save_json/save_jsonl（visidata/loaders/json.py#L136-L192）用getTypedValue走_rowdict()构造成字典序列化；save_txt（visidata/save.py#L225-L229）在单 Sheet 且可见列多于 1 列时自动转成save_tsv。这些都可以作为你编写 Saver 的活模板。

visidata.Path：超越文件系统的路径抽象

visidata.Path是 Python 内置pathlib.Path的包装（定义于 visidata/path.py#L182-L188），它额外支持非文件系统来源：URL、标准输入、归档（zip/tar）内的文件等。

• given属性是visidata.Path新增的，保存用户最初给定的原始字符串（含 shell 变量展开、~展开，见 visidata/path.py#L186）；
• 其余函数（exists、open、open_text、read_text、open_bytes、read_bytes、stat、with_name）是对pathlib.Path同名函数的包装，为非文件系统文件提供专门功能；
• 其他所有访问都会转发到内部的pathlib.Path对象，但对非文件系统文件通常不适用。

open_text（visidata/path.py#L287-L316）会使用vd.options.encoding与encoding_errors设置；__iter__（visidata/path.py#L170-L176）逐行迭代并自动更新进度。此外 VisiData 还提供vd.urlcache(url, days=1, text=True)（visidata/_urlcache.py#L9-L35），把 URL 内容缓存到本地Path再返回——URL 加载器常用它做离线缓存。

URL Scheme Loaders：处理foo://协议

当 VisiData 尝试打开一个 scheme 为foo的 URL（即foo://开头）时，它会调用openurl_foo(urlpath, filetype)。urlpath是一个UrlPath对象，带解析后 URL 的各元素属性。调度逻辑在openPath()中（visidata/_open.py#L103-L118）：先看有无显式 filetype 对应的open_<filetype>可覆盖（visidata/_open.py#L104-L109），否则取 scheme（支持+组合 scheme 取最后一段）查找openurl_<scheme>。

openurl_foo应当返回一个 Sheet，或调用error()。两种典型情况：

• URL 本身就指明特定 Sheet 类型（如magnet://），则直接构造该 Sheet；
• URL 只是到达另一种 filetype 的手段，则可以调用openSource传入一个知道如何抓取该 URL 的 Path-like 对象：

def openurl_foo(p, filetype=None): return openSource(FooPath(p.url), filetype=filetype)

openSource（visidata/_open.py#L173-L200）返回按给定 filetype 打开的未加载 Sheet，并支持把 kwargs 作为选项覆盖。

仓库内真实案例：openurl_http（visidata/loaders/http.py#L30）处理 http/https 及复合 scheme；openurl_imap（visidata/loaders/imap.py#L7-L9）从 URL 解析 hostname 构造ImapSheet；openurl_mysql（visidata/loaders/mysql.py#L24-L26）用urlparse拆出数据库名。这些实现的共同点：把 URL 解析逻辑与加载逻辑分离，URL 层只负责"变成某个 Sheet / 某个源"。

提交你的加载器

官方文档明确欢迎两种贡献方式：作为核心 VisiData 的加载器，或作为独立插件。提交前建议对照仓库中的贡献清单（dev/checklists/feature.md）逐项自检，并按上述"加载器性能测试清单"用大文件验证首行即时出现、进度更新与可取消性。测试方面，仓库在 tests/ 目录以.vd脚本 + golden 输出的形式为每种加载器维护了回归测试（如load-csv.tsv、load-json.tsv），编写新加载器时参照这些测试样例（tests/test.sh、dev/diff-test.sh）补上对应的.vd与 golden 文件，就能让格式回归有据可依。

从open_readme的四行样板到save_table的完整双工实现，VisiData 的加载器体系始终围绕同一组约定：open_<filetype>建 Sheet、iterload/reload产行、columns定义视图、guess_<filetype>辅助识别、save_<filetype>负责写出。掌握这五块拼图，任何数据源都能在几分钟内变成一张可交互、可搜索、可保存的 VisiData 表格。

• 数据分析
• CLI
• 数据可视化