Exco

Excel Comment ORM。在Excel文件中直接声明ORM规范描述。

它做什么

该软件包允许您在Excel文件的注释中直接声明ORM映射，然后使用它从其他类似文件中提取数据。

以下是一个模板示例。

支持动态位置、验证、假设和自定义解析器。

安装

pip install exco

简单用法

import exco
processor = exco.from_excel('./quickstart_template.xlsx')
result = processor.process_excel('./quickstart_data_file.xlsx')
print(result.to_dict())

另请参阅 快速入门笔记本

Exco块

Exco依赖于Excel注释中的yml块来构建规范。每个注释可以包含多个块。Exco块有三种类型：单元格块、表格块和列块。

单元格块

cellblock是包围在{{--和--}}之间的yml块。

{{--
key: some_int
parser: int
--}}

这意味着将此单元格解析为int，并将其以some_int键放入结果中。

其他高级功能如回退、定位器、假设、验证器是可选的。完整规范如下所示。

{{--
key: some_value
# Optional default at_comment_cell
locator: {name: at_comment_cell} 
assumptions: # Optional
    - {key: right_of, name: right_of, label: marker}
parser: int
# Optional
fallback: 7 
# Optional. Dict[name, value].
params: {} 
validators: # Optional
    - {key: between, name: between, low: 5, high: 10 }
metadata: {unit: km}
--}}

处理流程。

单元格处理流程是

1. 定位单元格
2. 检查假设
3. 解析
4. 验证

功能

key

结果将被放置的key。这是必需的。

fallback

这是最有用的一个，如果在定位单元格、测试假设、解析失败时。回退值将被假设。如果没有指定，则使用None值。（yml的none是null）。

locator

定位器是一个字典。键name是要用于定位单元格的类名。其他参数可以扁平化并放入同一字典中。这些参数将通过该类的构造函数传递。

如果省略了定位器，则假定它是at_comment_cell，该定位器将在模板中与注释单元格具有相同坐标的单元格中定位。

assumptions

字典列表。键key是检查的名称。name是在测试假设时使用的类的名称。其他参数可以扁平化并包含在同一个字典中。

parser

必需。解析器类的名称。

params

可选。参数名称到其值的字典。展开的值将通过解析器构造函数传递。

validations

可选。字典列表。每个字典都必须有key作为验证键和name，指定验证器的类名。要传递给验证器构造函数的其他参数也可以扁平化并在此字典中指定。

metadata

可选。元数据。可以放入任何对象的字典。该对象将被解析到结果中。

表格块

表格块用于指定表格的属性。表格块由{{--table和--}}包围。最简单的表格块是

{{--table
key: some_table
--}}

这通常是您需要的。下面是一个更复杂的示例

{{--table
key: some_table
# optional. default at_comment_cell
locator: {name: at_comment_cell}
# optional. default downward
item_direction: downward
end_conditions:
    - {name: all_blank}
    - {name: max_row, n: 10, inclusive: true}
--}}

功能

key

其中表格将被放置在结果中。表格的输出是一个字典列表，其中字典的键是在列块中指定的列名。

locator

可选。默认为at_comment_cell。表格锚单元格的定位器。与单元格块相同。

item_direction

可选。表格中项目的方向。默认向下。（向右或向下）

end_conditions

一个字典列表，指定每个终止条件。字典包含name和平坦化的参数。

如果满足任何终止条件，则表格的解析将终止。根据终止条件的类，它可能包括或不包括匹配的行。

列块

列块规范与单元格块非常相似。下面是一个最简单的示例。

{{--col
table_key: some_table
key: some_col
parser: int
}}

列块非常类似于单元格块。它是带有table_key而没有locator的单元格块。table_key告诉它属于哪个表格。它必须与表格块中定义的表格的key之一匹配。

提取值时列单元格的位置是从模板中表格块的相对位置计算的。

其他像回退、假设、验证等功能也以相同的方式支持。

内置函数

定位器

at_comment_cell

在模板中定位在注释单元格坐标处的单元格。

right_of

定位到给定标签的单元格或合并单元格右侧的单元格。在合并单元格的情况下，right_of将选择合并单元格的最右侧列和最上行作为目标，以便向右移动。

Parameters

• label 匹配的标签。
• n 可选。默认值为1。表示从标签单元格移动到定位单元格的列数。

search_right_of

在给定值的单元格右侧搜索非空单元格。

Parameters

• label 匹配的标签。
• max_empty_col_search 表示搜索非空单元格右侧标签的列数的最大值。

right_of_regex

使用正则表达式定位单元格右侧的单元格。类似地，在合并单元格的情况下，right_of_regex将选择合并单元格的右侧最列和最上行单元格。

Parameters

• regex 字符串用于正则表达式。
• n 可选。默认值是1。表示从正则表达式匹配单元格到定位单元格移动的列数。

below_of

定位给定标签下方单元格。在合并单元格的情况下，below_of将选择合并单元格的下方最行和最左列单元格。

Parameters

• label 匹配的标签。
• n 可选。默认值是1。表示从标签单元格到定位单元格跳过的行数。

search_below_of

搜索给定标签下方非空单元格。

Parameters

• label 匹配的标签。
• max_empty_row_search 表示搜索非空单元格下方标签的行数的最大值。

below_of_regex

使用正则表达式定位单元格下方单元格。类似地，在合并单元格的情况下，below_of_regex将选择合并单元格的下方最行和最左行单元格。

Parameters

• regex 字符串用于正则表达式。
• n 可选。默认值是1。表示从正则表达式匹配单元格到定位单元格移动的行数。

within

定位给定标签之间的单元格。此功能在给定标签的范围内搜索右侧或下方。如果是在右侧，该函数将逐行搜索，同时保持在给定标签的列范围内。如果是在下方，类似地，我们也将逐行搜索，同时保持在给定标签的行范围内。在此基础上，您还有权选择如何选择数据（右侧或下方），一旦在单元格范围内找到所需的关键值。

Parameters

• label 您要搜索的标签的单元格标签
• find 您要在标签的范围内找到的单元格的名称
• direction 您要搜索值的方向，选项有
  • right_of 这将在列的行之间搜索单元格的右侧
  • below_of 这将在行的行之间搜索单元格的下方
• perform 您要执行的操作以获取数据，您的选项是
  • right_of 从find标签的右侧获取值
  • below_of 从find标签的下方获取值
• n 在指定执行方向（right_of或below_of）中获取n个值

假设

left_cell_match

这在批量处理中非常有用，使我们能够检查我们是否有正确的左侧标签。

Parameters

• label 要检查是否匹配的字符串

解析器

string

将值解析为字符串。

int

将值解析为整数。

float

将值解析为浮点数。

date

将值解析为日期。

验证器

between

如果值在high和low之间（包含），则为有效。

Parameters

• high 上限值。
• low 下限值。

TableEndCondition

all_blank

如果所有列都为空，则评估为真。

max_row

如果包括解析行在内的行号（从1开始）大于或等于n，则评估为真。

Parameters

• n 行数
• inclusive 可选。默认为True。是否包含评估为真的行。

cell_value

如果行中的任何列包含匹配的cell_value，则评估为真。在行之前终止表。

Parameters

• cell_value 要匹配的单元格值。

取消引用

有两种类型的取消引用。

• 创建时间取消引用。类似于 <<A1>> 的字符串将被解析为模板文件中 A1 单元格的值。
• 提取时间取消引用。类似于 ==A1== 的字符串将被解析为提取文件中 A1 单元格的值。

以下是一个示例。

{{--
key: ==D2==
assumptions: # Optional
    - {key: right_of, name: right_of, label: <<A1>>}
parser: int
fallback: ==D3== 
--}}

处理具有不同名称的相同工作表

当要提取的 Excel 文件的工作表名称与模板文件中的不同时，请在 exco.from_excel() 中使用 sheet_name_checkers 参数创建具有工作表名称别名的 ExcelProcessor。

例如，当模板文件中的工作表名称为 'Test 1/1/2021'，但提取文件中的工作表名称可以变化，例如 'Test 2/2/2022'、'Test 3/3/2023' 等。

import exco

SheetName = str
SheetNameAliasChecker = Callable[[SheetName], bool]
test_sheet_checker: SheetNameAliasChecker = lambda sheetname: 'Test' in sheetname
checkers: Dict[SheetName, SheetNameAliasChecker] = {'Test 1/1/2021': test_sheet_checker}
processor = exco.from_excel(template_excel_path, sheet_name_checkers=checkers)

如果可能存在包含您不想提取的信息的隐藏工作表，请确保将 accept_only_visible_sheets 参数设置为 True。

processor = exco.from_excel(template_excel_path, sheet_name_checkers=checkers, accept_only_visible_sheets=True)

自定义定位器/解析器等。

请参阅 高级功能笔记本。但，本质上：

processor = exco.from_excel('./custom_locator/custom_locator_template.xlsx',
                            extra_locators={'diagonal_of': DiagonalOfLocator})

处理 .xls 文件。

Exco 不会读取 Excel 97-2003 工作簿 (.xls) 文件。请使用 XLS2XLSX 将 .xls 文件转换为支持的 .xlsx 格式。