Package: colorfultable
ColorfulTable模块简介ColorfulTable 是一个用于在终端屏幕上打印漂亮表格的 Python3 模块，使用它可以方便地构建表格并选择打印到终端屏幕上。支持 Linux、Windows 等平台预置 6 种表格边框样式，也支持自定义支持自定义每个单元格独立的字体颜色和背景色支持单元格内换行（如果储存对象是字符串）支持设置水平对齐方式和垂直对齐方式支持对指定行或列设置固定行高和列宽，也支持设置自适应行高和列宽按单元格储存任意受支持的 Python 数据类型（以对象的 str 方法显示单元格内容）输出函数支持自定义要打印的行数范围，是否打印表格标题行，支持输出到 Python 文件对象等等...函数文档Table类类初始化参数header必选位置参数，创建表格类Table类实例时的初始行（标题行），header数据类型应为可迭代对象，子数据类型则不限。例如：mytable1=Table(range(6))或者：mytable2=Table((1,2,3,))或者：mytable3=Table(['序号','姓名','学号','分数','备注'])alignh可选关键字参数，该参数是当未指定水平对齐方式时默认使用的水平对齐方式，可用值为 'l'、'left'、'c'、'center'、'r'、'right'，默认值为 'l'。alignv可选关键字参数，该参数是当未指定垂直对齐方式时默认使用的垂直对齐方式，可用值为 't'、'top'、'm'、'middle'、'b'、'bottom'，默认值为 't'。rowfixed可选关键字参数，该参数是表格默认行高，可用值为 0 或小于 MAX_ROW_HEIGHT（见第21条：limit）的正整数，默认值为 0（自适应行高）。colfixed可选关键字参数，该参数是表格默认列宽，可用值为 0 或小于 MAX_COLUMN_WIDTH（见第21条：limit）的正整数，默认值为 0（自适应列宽）。fbgc可选关键字参数，该参数是默认的单元格前景色和背景色，参数值数据类型应为包含颜色代码(字符串)的列表(list)、元组(tuple)、集合(set)，默认值为空。可用颜色代码见下表：序号颜色代码(字符串)代表颜色1fg_reset重置前景色和背景色2fg_red前景红色3fg_green前景绿色4fg_yellow前景黄色5fg_blue前景蓝色6fg_magenta前景品红色（紫色）7fg_cyan前景青色8fg_white前景白色9fg_brightblack前景亮黑色（灰色）10fg_brightred前景亮红色11fg_brightgreen前景亮绿色12fg_brightyellow前景亮黄色13fg_brightblue前景亮蓝色14fg_brightmagenta前景亮品红色（亮紫色）15fg_brightcyan前景亮青色16fg_brightwhite前景亮白色17bg_reset重置前景色和背景色18bg_red背景红色19bg_green背景绿色20bg_yellow背景黄色21bg_blue背景蓝色22bg_magenta背景品红色（紫色）23bg_cyan背景青色24bg_white背景白色25bg_brightblack背景亮黑色（灰色）26bg_brightred背景亮红色27bg_brightgreen背景亮绿色28bg_brightyellow背景亮黄色29bg_brightblue背景亮蓝色30bg_brightmagenta背景亮品红色（亮紫色）31bg_brightcyan背景亮青色32bg_brightwhite背景亮白色fill可选关键字参数，该参数是进行 addRow 或 addColumn 操作时，如果要添加的行或列长度不足，则用 fill 补足。参数值数据类型不限，默认值为空字符串 ''。style可选关键字参数，该参数是默认的表格边框风格类型，参数值数据类型应为 Style 的类实例，可用值见以下 "Style 类"。添加列方法 - addColumn方法原型addColumn(colindex,column=None)colindex 为索引参数，表示要插入列的位置。column 为要插入的列，参数值数据类型应为可迭代对象，子数据则不限类型。column 长度不足则用以上的类初始参数 fill  补足，过长则截断。可以不带 colindex 参数，默认添加列为末尾列。返回值None异常colindex 不是整数则触发 TypeError 异常。column 不是可迭代对象则触发 TypeError 异常。示例mytable=Table(['序号','姓名','学号','分数','备注'])mytable.addColumn(3,['科目','此行会被截断'])或者：mytable=Table(['序号','姓名','学号','分数','备注'])mytable.addColumn(['分数等级','此行会被截断'])添加行方法 - addRow方法原型addRow(rowindex,row=None)colindex 为索引参数，表示要插入行的位置。row 为要插入的行，数据类型应为可迭代对象，子数据则不限类型。row 长度不足则用以上的类初始参数 fill 补足，过长则截断。可以不带 rowindex 参数，默认添加列为末尾列。返回值None异常rowindex 不是整数则触发 TypeError 异常。row 不是可迭代对象则触发 TypeError 异常。示例：mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))获取列方法 - getColumn方法原型getColumn(colindex=-1)colindex 为索引参数，表示要获取的列的位置。可以不带 colindex 参数，默认获取最后一列。返回值包含列数据的列表。异常colindex 不是整数则触发 TypeError 异常；colindex 超出范围则触发 IndexError异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))col=mytable.getColumn(3)print(col)# ['科目', '打瞌睡']获取行方法 - getRow方法原型getRow(rowindex=-1)rowindex 为索引参数，表示要获取的行的位置。可以不带 rowindex 参数，默认获取最后一行。返回值包含行数据的列表。异常rowindex 不是整数则触发 TypeError 异常。rowindex 超出范围则触发 IndexError异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))row=mytable.getRow(0)print(row)# ['序号', '姓名', '学号', '科目', '分数', '备注']获取单元格数据方法 - getItem方法原型getItem(rowindex=-1,colindex=-1)rowindex 为索引参数，表示行索引。colindex 为索引参数，表示列索引。可以不带 rowindex 、colindex 参数之一或全部，不带的参数默认为 -1（最后一行或列）。如果不带 rowindex，则 colindex 需要以关键字参数方式指定。返回值单元格里的数据。异常rowindex 、colindex 不是整数则触发 TypeError 异常。rowindex 、colindex 超出范围则触发 IndexError异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))item=mytable.getItem(1,4)print(item)# 100获取单元格字符串方法 - getString与 getItem 大致相同，返回值为单元格里的数据的字符串形式。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))string=mytable.getString(1,4)print(string)# '100'覆写单元格数据方法 - writeCell方法原型writeCell(rowindex=None,colindex=None,*,value)rowindex 为索引参数，表示行索引。colindex 为索引参数，表示列索引。索引参数可以为 None 或整数。value 为必选参数，为要写入的值，不限数据类型，必须以关键字参数方式调用。可以不带 rowindex 、colindex 参数之一或全部，不带的参数默认为 None。rowindex  和 colindex 参数可用值为 None 或整数，当 rowindex  为 None，colindex 不为 None 时，以 value 覆写 colindex 所代表的整列数据，反之亦然。两个参数都为 None 时，以 value 覆写表格全部数据。当不带 rowindex 参数时，colindex 应以关键字参数方式调用，反之则不用。返回值None异常rowindex 、colindex 不是整数则触发 TypeError 异常。rowindex 、colindex 超出范围则触发 IndexError异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))mytable.writeCell(colindex=4,value=8)# 以 8 覆写第 5 列所有数据mytable.writeCell(1,value=8)# 以 8 覆写第 2 行所有数据mytable.writeCell(value=8)# 以 8 覆写整个表格所有数据mytable.writeCell(1,2,value=8)# 以 8 覆写第2行第3列单元格的数据清空单元格方法 - clearCell方法原型clearCell(rowindex=None,colindex=None)调用方法大致与 writeCell 方法相同，只是没有 value 参数。测试表格内容是否为空方法 -  isEmpty方法原型isEmpty(rowindex=None,colindex=None)索引参数使用方法与 writeCell 方法相同。测试表格内容是否全部非空方法 - isFull方法原型isFull(rowindex=None,colindex=None)索引参数使用方法与 writeCell 方法相同。删除列方法 - delColumn方法原型delColumn(colindex)参数 colindex 为要删除的列索引。返回值包含删除的列元素的列表。异常colindex 不是整数时触发 TypeError 异常。colindex 超出范围时触发 IndexError 异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))column=mytable.delColumn(5)# 删除第5列print(column)# ['备注', '']删除行方法 - delRow方法原型delRow(rowindex)参数 rowindex 为要删除的行的索引值。返回值包含已删除的行的元素的列表。异常rowindex 不是整数时触发 TypeError 异常。rowindex 超出范围时触发 IndexError 异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))row=mytable.delRow(0)# 删除第一行print(row)# ['序号', '姓名', '学号', '科目', '分数', '备注']设置列宽方法 - setColumnWidth方法原型setColumnWidth(colindex,width)参数 colindex 为要设置列宽的列索引；width 为要设置的宽度，可用值为 None、0 或小于 MAX_COLUMN_WIDTH（见第21条：limit）的正整数，0 代表自适应列宽。当 colindex 为 None 时，意为将所有列的列宽设置为 width。当只填一个参数时，该参数默认为 width，意为将所有列的列宽设置为 width。返回值None异常当 colindex 不为整数时触发 TypeError 异常。colindex 超出范围时触发 IndexError 异常。width 大于 MAX_COLUMN_WIDTH 时触发 ValueError 异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.setColumnWidth(0,0)# 将第一列的列宽设置为自适应宽度mytable.setColumnWidth(10)# 将所有列的列宽设置为 10设置行高方法 - setRowHeight方法原型setRowHeight(rowindex,height)参数 rowindex 为要设置行高的行索引；height 为要设置的行高，可用值为 None、0 或小于 MAX_ROW_HEIGHT（见第21条：limit）的正整数，0 代表自适应行高。当 rowindex 为 None 时，意为将所有行的行高设置为 height。参数使用方法与 setColumnWidth 方法相同，只是索引参数变为行索引值。设置单元格对齐方式方法 -  setAlignment方法原型setAlignment(rowindex=None,colindex=None,*,alignh=None,alignv=None)参数 rowindex 为行索引，可用值为 None 或整数；colindex 为列索引，可用值为 None 或整数。参数 alignh 为水平对齐方式，alignv 为垂直对齐方式，它们的可用值见前面的“类初始参数”。对于行索引 rowindex 和列索引 colindex，都不为 None 则表示设置对应单元格对齐方式；其中一个为 None 则表示设置整行或整列的对齐方式；都为 None 则设置整个表格所有的单元格对齐方式。对于 水平对齐方式 alignh 和 垂直对齐方式 alignv，可以只调用其中一个，调用哪个就设置什么对齐方式，但都必须以关键字参数方式调用。返回值None异常rowindex 和 colindex 不为整数时触发 TypeError 异常，超出范围则触发 IndexError 异常。alignh 和 alignv 不是有效选项时触发 ValueError 异常。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))mytable.setAlignment(0,1,alignh='c')# 设置第一行第二列所指单元格的水平对齐方式为居中对齐。mytable.setAlignmemt(alignv='m')mytable.setAlignment(None,None,alignv='m')#以上两种方法都是设置所有单元格的垂直对齐方式为居中对齐，但明显前面一种方法更方便，后面一种方法是没有必要的，因为行列索引参数的默认值就是 None，没必要再填一次。mytable.setAlignment(1,alignh='c',alignv='b')# 设置第一行所有单元格的水平对齐方式为居中，垂直对齐方式为底端对齐。此方法忽略的索引参数其实是 colindex，而不是 rowindex。mytable.setAlignment(colindex=2,alignh='r',alignv='m')mytable.setAlignment(None,2,alignh='r',alignv='m')# 以上两种方法都是将第三列所有单元格的水平、垂直对齐方式分别设置为 右对齐、居中对齐。要省略 rowindex，则 colindex 就需以关键字参数方式调用，否则就不能省略 rowindex 的值 None。设置单元格前景色和背景色方法 - setColor方法原型setColor(rowindex=None,colindex=None,*,clrs=None)索引 rowindex、colindex 使用方法与 setAlignment 方法相同。颜色参数 clrs 数据类型应为集合、元组或列表，集合里包含颜色码。可用颜色码见“类初始参数”中的表格。示例mytable=Table(['序号','姓名','学号','科目','分数','备注'])mytable.addRow(1,(1,'小明','123','打瞌睡',100))mytable.setColor(clrs={'fg_yellow','bg_red'})# 设置所有单元格的颜色为 {'fg_yellow', 'bg_red'}，即前景色：黄，背景色：红。mytable.setColor(None,0,clrs={'fg_red'})# 设置第一列所有单元格的前景色为红色（注：此时单元格的原有颜色会被清空，如果想要单元格的颜色不被清空，请用 getColor 方法获取单元格的颜色集合，再用集合的方法对获取到的颜色集合进行更改）设置表格边框风格方法 - setStyle方法原型setStyle(style)参数 style 的值应为 Style 类的实例，详细用法见末尾的“Style类”。设置填充对象方法 - defaultFill方法原型defaultFill(fill='')用于设置默认的填充对象，即添加行或列时，要添加的行或列的长度比原表格行或列的长度短时，使用 fill 填充至等长。参数 fill, 数据类型不限，默认值为空字符串 ''。输出表格方法 - show方法原型show(start=0,stop=None,*,color=True,header=True,footer=False,file=sys.stdout)start 和 stop 为要输出的表格的起始行和结束行（不包括标题行），数据类型应为整数。color 为是否要按设置的颜色将表格打印到终端上，值为 False 将按默认颜色打印（设置的颜色不会被清除，下次 color 为 True 时仍然可以按已经设置的颜色打印），数据类型应为布尔值。header 为是否显示标题行，数据类型应为布尔值。footer 为是否显示脚注，数据类型应为布尔值。file 为输出目标，可以是 Python 文件对象（Python file object），默认为标准输出流 sys.stdout。以上参数可以自由选择调用，也可以全部使用默认；后 4 个参数只能以关键字参数方式调用。最大行高列宽列数限制方法 - limit方法原型limit(item,value)参数 item 只接受以下字符串：MAX_ROW_HEIGHTMAX_COLUMN_NUMMAX_COLUMN_WIDTH参数 value 只接受大于 1 小于 300 的整数。当 item 值为 MAX_ROW_HEIGHT 时，设置行高最大限制为 value。当 item 值为 MAX_COLUMN_NUM 时，设置列数最大限制为 value。当 item 值为 MAX_COLUMN_WIDTH 时，设置列宽最大限制为 value。设置默认颜色方法 - defaultClr方法原型defaultClr(*value)参数 value 值类型应为字符串（颜色代码），参数个数不限。value 可用的颜色代码见 Table 类初始化参数 fbgc 的可用颜色码表格。异常当 value 值不是字符串时触发 TypeError 异常。当 value 值是不可用的颜色代码时触发 ValueError 异常。设置默认对齐方式方法 - defaultAlign方法原型defaultAlign(*,alignh=None,alignv=None)参数 alignh 为默认使用的水平对齐方式。参数 alignv 为默认使用的垂直对齐方式。两个参数都需要以关键字参数方式调用，不需要设置的对齐方式可以不写。异常当 alignh 为无效的值时触发 ValueError 异常。当 alignv 为无效的值时触发 ValueError 异常。重构 、刷新表格字符串形式方法 - refactorText方法原型refactorText(footer=False)footer 参数应为布尔型 bool（True、False），表示是否生成带脚注的表格字符串形式。用于主动重构、刷新表格的字符串形式，一般情况下都会自动调用（比如调用 show、getText 方法时）。如果你想获取 Table 类实例的“行”的字符串形式列表 rowTexts，则访问该属性前你应该先调用 refactorText 方法。获取整个表格的字符串形式方法 - getText方法原型getText(start=0,stop=None,header=True,footer=False,color=False)用于获取整个表格的字符串形式（即获取一个字符串，在终端上打印该字符串就是一个表格）。参数 start、stop、header、footer、color 与 show 方法同名参数用法一致。设置脚注方法 - setFoot方法原型setFoot(footnotes)参数 footnotes 应为包含字符串的列表 list 或元组 tuple。footnotes 中每一个元素（字符串）在表格脚注中都是一行（字符串超过表格宽度会自动换行），但也可以在字符串中增加换行符进行主动换行。异常当 footnotes 不是列表 list 或元组 tuple 中的一种时，触发 ValueError 异常。当 footnotes 中元素有非字符串 str 时，触发 ValueError 异常。获取脚注方法 - getFoot方法原型getFoot()该方法返回当前 Table 类实例的脚注列表（包含字符串 str 的列表 list）。外部可以用列表方法对该返回值进行操作，操作将直接对 Table 类实例的当前脚注列表生效。Style类类实例属性等号左边为属性，等号右边为默认值。cell_pad = ' '单元格内容左右两边的填充字符top_left = '┌'表格边框左上角字符top_cross = '┬'边框顶部三交叉点字符top_right = '┐'边框右上角字符top_horz = '─'顶部边框水平线字符bottom_left = '└'边框左下角字符bottom_cross = '┴'边框底部三交叉点字符bottom_right = '┘'边框右下角字符bottom_horz = '─'底部边框水平线字符left_cross = '├'左边框三交叉点字符left_vert = '│'左边框垂直线字符right_cross = '┤'右边框三交叉点字符right_vert = '│'右边框垂直线字符center_horz = '─'中间水平线字符center_vert = '│'中间垂直线字符center_cross = '┼'中间十字交叉点字符split_left = '╞'标题行与主体分隔线左边框三交叉点字符split_right = '╡'标题行与主体分隔线右边框三交叉点字符split_horz = '═'标题行与主体分隔线水平线字符split_cross = '╪'标题行与主体分隔线十字交叉点字符类初始化参数style例：mystyle=Style(style)参数 style 可用值为以下字符串：tablesimpleclassictable-asciisimple-asciiclassic-ascii通过选择不同的初始化参数，自动给类实例属性赋予不同的预设值，以此来达到不同的表格边框风格的目的。重置边框风格方法 - reset方法原型reset()将 Style 实例属性重置至默认属性。示例mystyle=Style('simple')mystyle.reset()# 重置至默认的 table 风格。选择预置表格边框风格方法 - choose方法原型choose(style)选择预置的边框风格，参数 style 可用值与 Style 类初始化参数可用值一致。异常当 style 值不是有效值时触发 ValueError 异常。示例：mystyle=Style('table')mystyle.choose('classic')# 将 mystyle 实例的边框风格属于改变为预置的 classic 风格。其他除了使用 choose 方法或选择不同的初始化参数来选择预置的表格边框风格外，还可以直接对类实例属性进行更改，以期达到更精确的定制化需求。直接修改类实例属性时值得注意的事项：a) 类实例属性值仅接受字符串类型数据；b) 类实例属性值并不限制字符数量，不限制字符宽度（例如字母和汉字的字符宽度就不一样），所以设置类实例属性时就需要用户自行注意不同属性需要同样的总字符宽度以实现表格边框的对齐，否则就会出现表格边框错位的情况。例如：当center_cross被设置为两个字母oo时，作为同一垂直方向线上的其他属性top_cross、center_vert、bottom_cross也都应该设置属性值为两个字母宽度的字符串；或某些属性设置为空字符串时，其他一些属性也要设置为空字符串，其他属性同理。后续可能会增加对属性值的自动限制。见目录下的 demo.py 文件。最后# 表格中中文与英文混合使用时是否对齐与字体、运行的控制台类型有关
# windows 平台上，程序输出于 cmd、PowerShell 时表格里无论中英文对齐都非常好
# 以上终端（不限）建议把自动折行关掉，否则表格超过终端屏幕宽度时自动折行会使表格变成一团糟
# IDLE、PyCharm 等 IDE 的自带终端中，中文基本上无法对齐
# 这是第一个可用版本，BUG 比较多，功能也相对简单，后续会添加新功能
# 文档写的也比较匆忙，可能错漏比较多，后续会不断修正
# 因为源码经过好几次重构，所以函数文档基本都丢了还没有来得及重新写（已经写了的函数文档可能也有跟源码不对应的情况），后续提交会不断补上。