🐯 Recorder

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

支持 csv、xlsx、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、json、txt 四种记录格式。

xlsx：表格文件，数据内容可保留类型。
csv：表格文件，数据以文本方式记录。
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

🌺 设置单元格样式

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

设置样式只对 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()`

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

参数名称	类型	默认值	说明
`new_path`	`str` `Path`	`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.table()`

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

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

返回： 当前设置对象

📌 `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

🐯 Recorder

🐘 创建对象

➕ 添加数据

✔ 记录单个数据

✔ 接收一行多个数据

✔ 接收多行数据

🧾 指定工作表

📃 指定默认工作表

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

💾 写入文件

✍ 自动写入

✍ 手动写入

⚠️ 注意事项

📑 文件格式

🔖 自动识别文件格式

🔖 手动指定文件格式

💡 示例

🌺 设置单元格样式

☘️ 跟随上一行

☘️ 指定样式

♾️ Recorder 对象的方法

📌 add_data()

📌 record()

📌 clear()

⚙️ Recorder 对象参数设置

📌 set.path()

📌 set.cache_size()

📌 set.file_type()

📌 set.table()

📌 set.head()

📌 set.before()

📌 set.after()

📌 set.styles()

📌 set.col_height()

📌 set.follow_styles()

📌 set.fit_head()

📌 set.encoding()

📌 set.delimiter()

📌 set.quote_char()

📌 set.show_msg()

🔣 Recorder 对象的属性

📌 path

📌 type

📌 data

📌 cache_size

📌 table

📌 encoding

📌 delimiter

📌 quote_char

📌 before

📌 after

📌 show_msg

♾️ `Recorder` 对象的方法

📌 `add_data()`

📌 `record()`

📌 `clear()`

⚙️ `Recorder` 对象参数设置

📌 `set.path()`

📌 `set.cache_size()`

📌 `set.file_type()`

📌 `set.table()`

📌 `set.head()`

📌 `set.before()`

📌 `set.after()`

📌 `set.styles()`

📌 `set.col_height()`

📌 `set.follow_styles()`

📌 `set.fit_head()`

📌 `set.encoding()`

📌 `set.delimiter()`

📌 `set.quote_char()`

📌 `set.show_msg()`

🔣 `Recorder` 对象的属性

📌 `path`

📌 `type`

📌 `data`

📌 `cache_size`

📌 `table`

📌 `encoding`

📌 `delimiter`

📌 `quote_char`

📌 `before`

📌 `after`

📌 `show_msg`