Skip to content

🐯 Recorder

Recorder的功能简单直观高效实用，只做一个动作，就是不断接收数据，按顺序往文件末尾添加。可以接收单行数据，或二维数据一次写入多行。

支持 csv、xlsx、jsonl、json、txt 五种格式文件。

🐘 创建对象

初始化参数 类型 默认值 说明
path str
Path		 None 文件路径，若不存在会自动创建，如存在则在最后追加数据
cache_size int None 缓存数据条数，为0时不自动记录数据

示例：

from DataRecorder import Recorder

r = Recorder(path='data.csv', cache_size=500)

➕ 添加数据

Recorder支持非常灵活的数据输入，可一次接收单条或多条数据。

  • 接收str、int、float、openpyxl 的Cell对象，或其它类型对象时，将其作为一个数据独占一行来记录。

  • 接收list、tuple、dict时，会将其中数据记录为一行。

  • 接收二维list或tuple时，会记录为多行。

✔ 记录单个数据

r.add_data('abc')  # 接收str数据
r.add_data(123)  # 接收int数据
r.add_data(cell)  # 接收openpyxl Cell对象（value为'def'）

Tips

接收 openpyxl 的Cell对象时，会记录其value值。

文件内容：

abc
123
def

✔ 接收一行多个数据

r.add_data({'a': 1, 'b': 2})  # 接收dict数据
r.add_data([123, 'abc'])  # 接收list数据
r.add_data((123, 'abc'))  # 接收tuple数据

Tips

接收dict数据时，会记录其value值。如果一个新文件，接收的第一条数据是dict格式，会自动根据其key值创建表头。

文件内容：

a b
1 2
123 abc
123 abc

✔ 接收多行数据

r.add_data([{'a': 1, 'b': 2}, {'a': 3, 'b': 4}])  # 接收多个dict
r.add_data([(1, 2), (3, 4)])  # 接收二维list
r.add_data(((1, 2), (3, 4)))  # 接收二维tuple

其中，接收多个dict的数据时，如果是新建文件，会自动以'a'、'b'生成表头。

文件内容：

a b
1 2
3 4
1 2
3 4
1 2
3 4

🧾 指定工作表

可为记录器指定要操作的工作表，如工作表不存在，程序会自动创建。

如不对工作表进行任何设置，程序会使用活动工作表。

但只有 xlsx 文件可以指定。

📃 指定默认工作表

用set.table()方法指定默认工作表，之后所有添加的数据都会默认添加到该工作表。

from DataRecorder import Recorder

r = Recorder('demo.xlsx')
r.set.table('sheet1')

📃 每个数据独立指定工作表

使用add_data()方法的table参数可为每条数据指定工作表。

r.add_data('abc', table='sheet2')

💾 写入文件

✍ 自动写入

当接收数据到达指定条数，会触发写入文件动作，同时清空缓存。

如果写入时文件被打开而无法写入，会自动等待文件关闭再写入。

在写入文件开始和结束时，默认会打印提示，提醒用户此时不要关闭进程。如须设置不显示，可把show_msg参数设置为False。

from DataRecorder import Recorder

r = Recorder('data.csv')
r.add_data(123)  # 程序结束时自动写入文件

✍ 手动写入

可在程序中调用record()来提前执行写入动作。

from DataRecorder import Recorder

r = Recorder('data.csv')
r.add_data(123)
r.record()  # 手动调用写入方法

⚠️ 注意事项

  • 切勿在文件正在写入的时候关闭进程，以免造成文件损坏。

  • 强烈建议在程序结束时显式调用record()保存数据。

📑 文件格式

Recorder支持 xlsx、csv、jsonl、json、txt 五种记录格式。

  • xlsx：表格文件，数据内容可保留类型
  • csv：表格文件，数据以文本方式记录
  • jsonl：每行都是 json 格式的文本文件
  • json：以 json 格式记录数据
  • txt：每行数据为文本格式，多个数据间用空格分隔

🔖 自动识别文件格式

指定记录文件路径后，程序会根据文件后缀判断使用哪一种格式。

如果没有后缀或不是这四种之一，会以 csv 方式进行记录。

r = Recorder('abc.csv')  # 自动以csv方式记录数据

🔖 手动指定文件格式

如果文件路径没有后缀，或想指定与后缀不一致的记录方式，可用set.type()指定记录格式。

r = Recorder('abc')
r.set.type('csv')

💡 示例

有以下代码：

data = (('姓名', '年龄'),
        ('张三', 20),
        ('李四', 22))
r.add_data(data)

xlsx 格式保存内容：

姓名 年龄
张三 20
李四 22

其中姓名列单元格格式为文本，年龄列单元格格式为数字。

csv 格式保存内容：

姓名,年龄
张三,20
李四,22

json 格式保存内容：

[["\u59d3\u540d", "\u5e74\u9f84"], ["\u5f20\u4e09", 20], ["\u674e\u56db", 22]]

txt 格式保存内容：

姓名 年龄
张三 20
李四 22

🗂️ 备份文件

👋 自动备份

使用set.auto_backup()设置自动备份后，程序会在每写入一定次数时触发自动备份，把当前文件备份到指定位置。

from DataRecorder import Recorder

recorder = Recorder()
recorder.set.auto_backup(interval=10, path='backup')

🖐️ 手动备份

调用backup()即可当前文件手动备份到指定位置。

from DataRecorder import Recorder

recorder = Recorder()
recorder.backup(path='backup')

🌺 设置单元格样式

可以对新增数据行的单元格样式进行设置，有两种模式：跟随上一行、直接指定样式。

设置样式只对 xlsx 格式文件有效。

☘️ 跟随上一行

在对已有格式的文件添加数据时，这种方式可以使新行样式自动保持与原有行一致。

from DataRecorder import Recorder

r = Recorder('demo.xlsx')
r.set.follow_styles(on_off=True)  # 设置跟随上一行的样式

r.add_data('test')
r.record()

☘️ 指定样式

也可以创建一个CellStyle对象列表，指定新行使用这些样式进行添加。

列表中每个样式对象对应一列，不设置样式的设为None。

如果直接传入一个CellStyle对象，则整个新行都用相同的样式。

指定样式的优先级比跟随上一行样式高。

from DataRecorder import Recorder
from DataRecorder.style import CellStyle

r = Recorder('demo.xlsx')
c1 = CellStyle()  # 创建样式对象
c1.font.set_color('red')  # 设置文本颜色
c2 = CellStyle()
c2.font.set_color('blue')

r.set.styles((c1, c2))  # 设置新行样式

r.add_data('test')
r.record()

♾️ Recorder 对象的方法

📌 add_data()

此方法用于添加数据到缓存，可接收一个、一行或多行数据。

参数名称 类型 默认值 说明
data Any 必填 可接收任意格式，接收一维list、tuple和dict时记录为一行，接收二维数据时记录为多行
table str
bool		 None 当前数据要插入的表格名称，仅支持 xlsx 格式。为None表示用set.table()方法设置的值，为bool表示活动的表格

返回：None

📌 record()

此方法用于把数据记录到文件，然后清空缓存。

参数： 无

返回类型 说明
str 文件路径

📌 backup()

此方法用于当前记录的文件保存一份副本。

参数名称 类型 默认值 说明
path str
Path		 'backup' 文件夹路径，默认保存到当前路径下'backup'文件夹
name str None 保存的文件名，可不包括扩展名，为None使用记录目标指定的文件名
返回类型 说明
str 文件路径

📌 clear()

此方法用于清空现有缓存。

参数：无

返回：None

⚙️ Recorder 对象参数设置

Recorder对象的设置使用set.****()的方式进行。

可进行链式操作，如set.fit_head().cache_size(30)。

📌 set.path()

此方法用于设置文件路径，更改时会自动保存缓存数据到文件。

参数名称 类型 默认值 说明
path str
Path		 必填 文件路径
file_type str None 文件类型，为None则从文件名中获取

返回： 当前设置对象

📌 set.cache_size()

此方法用于设置缓存大小，指定采集多少条自动记录到文件，为0时不自动记录。

参数名称 类型 默认值 说明
size int 必填 缓存数据条数

返回： 当前设置对象

📌 set.file_type()

此方法用于指定文件类型，无视文件后缀名。

参数名称 类型 默认值 说明
file_type str 必填 在四种支持的类型中选择

返回： 当前设置对象

📌 set.auto_backup()

此方法用于设置自动备份相关参数。

参数名称 类型 默认值 说明
interval int None 自动保存多少次时触发备份，为0表示不自动备份，为None时不修改已设置值（初始为0）
path str
Path		 None 备份文件存放路径，为None时不修改已设置值（初始为'backup'）
new_name bool None 是否用新名称备份，为None时不修改已设置值（初始为True）

返回： 当前设置对象

📌 set.table()

此方法用于处理 xlsx 文件时指定数据表。

参数名称 类型 默认值 说明
name str 必填 数据表名称

返回： 当前设置对象

📌 set.head_row()

此方法用于指定哪行为标题行（初始为1），只支持 csv 和 xlsx 格式文件。

参数名称 类型 默认值 说明
num int 必填 行号，1 开始

返回： 当前设置对象

📌 set.head()

此方法用于给表格文件设置表头，只支持 csv 和 xlsx 格式文件。

参数名称 类型 默认值 说明
head list
tuple		 必填 表头内容
table str None 要设置的表名称，为None则设置活动表格
to_file bool True 是否改变文件中的表头，如为False可使运行时使用的表头和文件的不一致

返回： 当前设置对象

📌 set.before()

此方法用于设置对象before参数内容，设置前会先保存缓存数据。

before内容的用法将在 “进阶用法” 章节说明。

参数名称 类型 默认值 说明
before Any 必填 每行数据前要添加的内容，单个数据或列表数据皆可

返回： 当前设置对象

📌 set.after()

此方法用于设置对象after参数内容，设置前会先保存缓存数据。

after内容的用法将在 “进阶用法” 章节说明。

参数名称 类型 默认值 说明
after Any 必填 每行数据后要添加的内容，单个数据或列表数据皆可

返回： 当前设置对象

📌 set.styles()

此方法用于设置新增数据行的格式，xlsx 格式时才生效。

只传入一个CellStyle对象时整行使用相同格式。

以列表形式传入多个CellStyle对象时为每列设置不同格式，不设置格式的列填None。

要清除设置的样式则传入None。

参数名称 类型 默认值 说明
styles CellStyle
list
tuple
None		 必填 单元格格式对象组成的列表或单个对象

返回： 当前设置对象

📌 set.col_height()

此方法用于设置新增数据的行高，xlsx 格式时才生效。

参数名称 类型 默认值 说明
height float 必填 行高

返回： 当前设置对象

📌 set.follow_styles()

此方法用于设置新增数据的的样式和行高是否跟随文档最后一行，xlsx 格式时才生效。

注意

set.styles()的优先级比set.follow_styles()高。

参数名称 类型 默认值 说明
on_off bool 必填 bool类型表示开或关

返回： 当前设置对象

📌 set.fit_head()

此方法用于设置dict数据是否自动匹配表头，xlsx 和 csv 格式时才生效。

参数名称 类型 默认值 说明
on_off bool True bool类型表示开或关
add_new bool False 数据中有表头不存在的列时是否自动添加到表头，on_off为True时才有效

返回： 当前设置对象

📌 set.encoding()

此方法用于设置编码格式。

参数名称 类型 默认值 说明
encoding str 必填 编码名称

返回： 当前设置对象

📌 set.delimiter()

此方法用于设置 csv 文件分隔符，csv 格式时才生效。

参数名称 类型 默认值 说明
delimiter str 必填 csv 文件分隔符

返回： 当前设置对象

📌 set.quote_char()

此方法用于设置 csv 文件引用符，csv 格式时才生效。

参数名称 类型 默认值 说明
quote_char str 必填 csv 文件引用符

返回： 当前设置对象

📌 set.show_msg()

此方法用于设置是否显示运行信息。

参数名称 类型 默认值 说明
on_off bool 必填 bool类型表示开或关

返回： 当前设置对象

🔣 Recorder 对象的属性

📌 path

此属性以字符串方式返回当前记录的文件路径。可赋值设置。更改时会自动保存缓存数据到文件。

类型：str

📌 type

此属性以字符串方式返回当前文件的类型。可赋值设置，即可无视文件后缀指定记录格式。

类型：str

📌 data

此属性返回当前保存在缓存里的数据。

返回类型 说明
list 非 xlsx 格式文件以list格式返回结果
dict xlsx 格式文件时以dict格式返回结果

📌 cache_size

此属性返回缓存的大小，表示记录的条数。

类型：int

📌 table

此属性返回当前处理的数据表，处理 xlsx 文件时才生效。

返回类型 说明
str 设置具体表名时返回表名字符串
None 为None时表示记录到活动表格

📌 encoding

此属性返回当前文件的编码方式，默认为'utf-8'。

类型：str

📌 delimiter

此属性返回 csv 文件使用的分隔符，默认为','。

文件格式为 csv 时才生效。

类型：str

📌 quote_char

此属性返回csv 文件使用的引用符，默认为'"'。

文件格式为 csv 时才生效。

类型：str

📌 before

此属性返回当前对象设置的before内容，before参数内容的用法将在 “进阶用法” 章节说明。

类型：Any

📌 after

此属性返回当前对象设置的after内容，after参数内容的用法将在 “进阶用法” 章节说明。

类型：Any

📌 show_msg

此属性用于设置是否打印程序运行时产生的提示信息。

类型：bool