Rich Columns 窄终端报 ZeroDivisionError,固定列宽可能算出零列
Rich 15.0.0 的固定列宽加 padding 超出可用区域时,Columns 可能得到零列。可以去掉固定列宽或在窄窗口逐条输出,处理后核对条目数量与顺序。
Rich 的 Columns 在普通终端能显示,窗口缩窄后却抛出:
ZeroDivisionError: integer modulo by zero
Rich 15.0.0 的一个触发条件是:显式指定了列宽,而“列宽加间隔”大于当前渲染区域。列数被算成零,随后排列元素时对零取模。这里要看实际可用区域;嵌套在 Panel 或其他布局里时,它可能比整个终端更窄。
固定列宽把列数算成了零
例如终端宽度为 16,列宽也指定为 16,但仍保留默认的左右 padding:
from rich.columns import Columns
from rich.console import Console
console = Console(width=16)
console.print(Columns(["alpha", "beta"], width=16))
15.0.0 这条分支按 可用宽度 // (列宽 + 间隔) 计算列数。默认 padding 为 (0, 1),这里的分母是 17,结果为零。分母为正时,若它恰好等于可用宽度,商仍是 1;只有可用宽度更小才会算出零列。
还有另一种输入错误:width=0 且 padding 也为零,可能在算列数时直接除零。它与得到零列之后再取模的位置不同,不能都归为终端太窄。
不必固定列宽时,让 Columns 自动排列
希望展示的是一组完整条目,而不是严格的定宽网格,可以去掉 width:
console.print(Columns(["alpha", "beta"]))
自动路径会根据内容和当前区域选择排列方式,避免进入这个固定宽度计算分支。内容本身比终端长时,仍要按应用需要决定换行、裁切或其他展示方式,不能把“不抛异常”当作文字都已完整可见。
如果界面必须定宽,应在进入布局前保证列宽为正,并让列宽与 padding 符合当前区域。不要把进程启动时的终端宽度永久缓存下来;窗口缩放、输出重定向或嵌套容器都可能改变实际约束。
对于本来就很窄的输出,直接逐条输出通常更合适:
items = ["alpha", "beta"]
for item in items:
console.print(item)
这种写法改变了多列外观,但保留了条目。是否允许这个降级由界面决定,不需要修改 Rich 安装目录里的私有排列函数。
验收包含窄窗口和嵌套区域
截至 2026 年 10 月 24 日,正式 15.0.0 仍保留上述固定宽度实现,不能把外部补丁里的“至少一列”当成已安装版本的行为。升级时仍应核对正式版本包含的实现。
验证时至少覆盖正常宽度、恰好放下一列、略窄于一列,以及实际使用的嵌套布局。检查条目数量、顺序、中文或宽字符的换行,并保留空列表的行为。若采用逐条输出,确认 CLI 的其他调用方没有依赖原来的多列文本格式。


