startables for Python

Python包，包含读取/写入StarTable格式文件的数据结构和功能，并包含和操作其中信息。

本项目

与我们交流

有关特定于此Python包的功能请求和错误，请参阅此GitHub项目的issue tracker。

有关StarTable格式规范的更广泛问题，请参阅 StarTable标准页面。

贡献和探索

欢迎贡献，特别是如果它们与您之前在issue tracker中讨论或发布的任何问题相关。

安装

在PyPI上可用

pip install startables

以及在conda-forge上

conda install startables -c conda-forge

示例用法

import startables as st  # << recommended import idiom
import pandas as pd

# Build table manually
df = pd.DataFrame(data=[[float('nan'), 'gnu', 3], [4, 'gnat', '{{(+ x y)}}']], columns=['a', 'b', 'c'])
col_specs = {n: ColumnMetadata(Unit(u)) for n, u in zip(['a', 'b', 'c'], ['-', 'text', 'm'])}
table_x = st.Table(df=df, name='some_table', col_specs=col_specs, destinations={'success', 'glory'})

# Accessing Table contents: use Bundle.df pandas.DataFrame interface
print(table_x.df['b'])

# Read bundle of tables from file
b = st.read_csv('animal_farm_startable_file.csv')

# Make new bundle containing a subset of this bundle's tables by name and/ or destination
farm_bundle = b.filter(name_pattern='farm')  

# Accessing tables in bundle: use Bundle.tables List interface
for t in b.tables:
    print(t.name)
# Add tables to bundle
b.tables.append(table_x)

# Remove tables from bundle by name and/or destination
removed_tables = b.pop_tables(destination='my_farm')  # tables now removed from b

# ... More examples to come ...

对象模型

表格

表格包含一个单一的StarTable表格块，包括表名、目标字段和等长列，每个列包含一个值列表，并具有名称和元数据（目前包括一个单位字段和一个（尚未完全实现的）备注，两者都是字符串）。

表格内容存储在pandas DataFrame中。Table.df允许用户读写这个DataFrame。表格列名存储为DataFrame列（Series）名称。列单位单独存储。

用户可以使用pandas.DataFrame API随意修改DataFrame，甚至完全替换DataFrame。然而，引入表格规范中没有覆盖的列名将破坏表格。除此之外，删除列、添加/删除行、编辑单元格等操作都是可以的，不应该破坏任何东西。

包

包是用于存放一个或多个属于一起的表格的容器，通常是因为它们

• 有共同的来源，例如来自同一个文件或文件结构，并且/或者
• 被认为有共同上下文，特别是在评估表达式时

包被设计为文件I/O的主要接口。read_csv()和read_excel()函数分别读取CSV和Excel格式的StarTable文件，并都返回一个包，而Bundle.to_csv()和Bundle.to_excel()将一系列表格写入这些相同的文件格式。

其他类

TableOrigin包含指示给定表格来源的信息，用于可追溯性。目前它只是一个包含单个字符串的占位符。

ColumnMetadata是一个容器类，用于存储列的单位（以及自由文本备注，尽管这还没有与读写方法绑定，所以作用有限）。表格的列通过提供包含列名:ColumnMetadata的字典来指定，该字典涵盖了（至少）表格的子DataFrame中存在的所有列名。

表达式

表格单元格不仅允许包含文字值，还可以包含Lisp表达式。

Table.evaluate_expressions(context)将返回一个经过评估的表达式（如果有）的表格，基于给定上下文。也可以指定inplace=True以原地执行此操作。

Bundle.evaluate_expressions(context)执行相同操作，但针对所有子表。

单位转换

根据UnitPolicy，可以转换表格的单位。

UnitConversion定义了如何将给定的源单位转换为关联的参考单位。

km_m = ScaleUnitConversion(src_unit=Unit('km'), ref_unit=Unit('m'), ref_per_src=1000)
km_m.to_ref(42)  # returns 42000
km_m.from_ref(2000)  # returns 2

UnitPolicy包含任意数量的UnitConversion，但限制是任何源单位只能关联到一个参考单位，即不能包含从'mile'到'km'的UnitConversion和从'mile'到'm'的另一个UnitConversion（但可以包含从'km'到'm'的UnitConversion和从'mile'到'm'的另一个UnitConversion）。参考单位本身自动作为源单位添加，通过IdentityUnitConversion将自己作为自己的参考单位。然后可以在共享相同参考单位的任何两个源单位之间进行转换。

C_K = LinearUnitConversion(Unit('°C'), Unit('K'), slope=1, intercept=273.15)
cup = CustomUnitPolicy([
    ScaleUnitConversion(Unit('km'), Unit('m'), 1000),
    ScaleUnitConversion(Unit('mm'), Unit('m'), 0.001),
    IdentityUnitConversion(Unit('metre'), Unit('m')),   # alias of a reference unit
    C_K, 
    C_K.alias(src_unit_alias=Unit('deg_C'))  # alias of a source unit
    ])

cup.convert(42, from_unit=Unit('m'), to_unit=Unit('mm'))  # returns 42000
cup.convert(42, from_unit=Unit('mm'), to_unit=Unit('metre'))  # returns 0.042
cup.convert(42, from_unit=Unit('km'), to_unit=Unit('mm'))  # returns 42000000
cup.convert_to_ref(20, src_unit=Unit('deg_C'))  # returns 293.15
cup.ref_unit(src_unit=Unit('°C'))  # returns Unit('K')

表格的单位将根据UnitPolicy逐列转换。

• Table.convert_to_ref_units()通过调用UnitPolicy.convert_to_ref()将每个列转换为UnitPolicy参考单位。

• Table.convert_units()将转换为每个列明确指定的新单位。

• Table.convert_to_home_units()是Table.convert_units()的特殊情况，它将转换回表格的“主单位”。“主单位”保存在表格的col_specs中，是创建表格（无论是手动还是从文件读取）时使用的列单位，除非后来明确更改。

单位转换不支持表达式。必须在单位转换之前评估表达式。

更新日志

本项目从私有服务器迁移到GitHub，版本号为v0.8.0。此前的更改不包括在GitHub仓库中；尽管如此，0.8.0之前的变更记录在此处记录。PS-##以下是指向私有服务器上遗留的YouTrack问题跟踪器中的问题编号。这些编号保留原样，以供历史记录。

本项目遵循语义化版本控制。变更记录遵循keepachangelog.com上发布的指南。

未发布

在即将发布的版本中，以下项目将...

新增

• {...蝉鸣声...}

0.8.5 - 2020-17-12

修复

• pandas.read_excel()现在使用engine='openpyxl'调用，以确保与.xlsx文件的兼容性

0.8.4 - 2019-12-05

修复

• Bundle.to_csv()在文件头和其余部分之间添加分隔符，以方便使用read_csv()进行往返读取。这是一个快速修复方案，因为真正的问题出在read_csv()解析器上。

0.8.3 - 2019-10-30

新增

• #2：新增read_bulk()便捷函数，可一次性将多个StarTable文件读入单个Bundle。
• 新增import_from_word()实用函数，用于解析Microsoft Word *.docx文件中的表格块。

0.8.2 - 2019-10-30

新增

• #5：为ColumnMetadata新增可选属性format_str：格式化字符串，指定在写入文件时使用Bundle.to_csv()和Bundle.to_excel()时如何格式化列的值。
• #6：为Bundle.to_csv()和Bundle.to_excel()新增可选的header参数，允许在创建的文件顶部写入自由文本标题。此外，为Bundle.to_excel()新增可选的header_sep参数，指示用于分隔多列标题的分隔符。

0.8.1 - 2019-09-05

新增

• 更新了setup.py和setup.cfd，以便在PyPI上正确发布。

0.8.0 - 2019-09-03

更改

• read_csv()的第一个参数的名称从stream更改为filepath_or_buffer。自0.7.3以来，名称stream与预期类型不一致，即str或pathlib.Path（除TextIO流之外）。新的名称filepath_or_buffer与pandas.read_csv()一致。此更改将破坏使用stream作为命名参数的代码，尽管我们希望这种情况很少，如果不是从未发生。
• 移除了对openpyxl版本的限制（之前限制为< 2.6）。这是对PS-49的更少糟糕的修复。

修复

• PS-52 read_csv()在输入流时抛出警告；请求文件名
• PS-53 Bundle.to_csv()在列名不是字符串时失败

0.7.3 - 2019-02-27

修复

• 环境.yml中的openpyxl<26依赖项
• PS-19 如果CSV文件的第一行没有足够的列分隔符，则从CSV文件中读取可能会失败
• PS-48 通过允许非标准格式的.csv文件来提高startables python库的兼容性
• PS-50 从Excel导出的CSV文件导致第一张表由于UTF-8-BOM而无法读取

0.7.2 - 2019-02-18

修复

我们依赖的openpyxl版本2.6.0（几周前发布），包含重大破坏性更改（这在一定程度上违反了语义化版本控制中较小版本更新的精神...）并且这些破坏性更改确实破坏了startables。为了解决这个问题，现在将openpyxl版本号固定为<2.6在startables conda包配方中。

0.7.1 - 2018-11-30

更改

• 破坏性更改出现在Bundle.filter()和Bundle.pop_tables()方法中
  • 参数exact_name重命名为name，以与目的地相关参数的命名保持一致。
  • 签名中参数的顺序已更改为 (name, name_pattern, destination, destination_pattern, ignore_case)
  • PS-43 名称和目的地过滤器现在默认为不区分大小写。可以通过设置参数 ignore_case=False 再次使其区分大小写。

新增

• PS-41 使用正则表达式对目的地进行过滤

0.7.0 - 2018-11-28

本版本的所有更改都解决了 PS-27: 在Bundle中添加/删除表格

更改

破坏性变更 在 Bundle 中

• 方法 tables 已重命名为 filter。现在返回一个包含过滤后表格的 Bundle（即原始 Bundle 的子集），而不是返回一个 List[Table]。
• 引入了属性 tables（不要与同名的前者方法混淆）。返回存储在此 Bundle 中的内部表格列表。
• 所有与列表相关的操作都委托给了由 tables 属性返回的列表。特别是
  • 现在可以通过调用 Bundle.tables 的 append() 和 extend() 方法将 Table 添加到 Bundle（这是这一重大变化的主要驱动因素）。
  • 已删除魔法方法 __getitem__、__iter__ 和 __len__。

新增

• 方法 Bundle.pop_tables() 用于 通过名称和/或目的地选择性地移除 Bundle 的成员表格，并返回已删除的表格。（这是这一重大变化的另一个主要驱动因素。）

0.6.1 - 2018-11-22

更改

• PS-2 现在保留目的地的顺序。表目的地现在可以提供为任何 Iterable（从 Set 更改为 Iterable），然后在内部存储为 List，从而保留现有顺序（如果有）。可能破坏性的变更：在向 Table 提供目的地时遇到任何重复项将引发 ValueError，无论是从文件中读取还是程序化读取。（因为重复项确实没有意义。）在以前，使用 read_csv 和 read_excel 从文件中读取时，会静默地删除重复项，并且程序化地（严格主义者请避免）是不可能的，因为必须作为 Set 提供。

0.6.0 - 2018-11-20

新增

• 引入：单位转换机制 PS-10
• 在 windwiki 上发布此说明书的脚本
• PS-8 当解析表达式单元格时，现在提供了更友好的错误消息，引导用户到有问题的单元格

更改

• PS-35 Python 版本要求放宽到 3.6 和更高版本（以前严格为 3.6）

已移除

• PS-33 记录日志。现在已删除。它为客户代码日志中产生了太多的噪音。

0.5.5 - 2018-09-10

更改

• PS-15 read_csv() 和 read_excel() 现在接受 'nan'、'NaN' 和 'NAN' 作为有效的无数据标记。以前，仅接受 '-'。

0.5.4 - 2018-09-07

修复

• PS-28 文本列中的数值数据不会读取。

0.5.3 - 2018-09-07

修复

• PS-5 read_excel() 和 read_csv() 会忽略零行的表块。

0.5.2 - 2018-09-07

更改

• PS-14 read_csv() 现在将 *args 和 *kwargs 传递给 pandas.read_csv()，因此用户现在可以利用 pandas.read_csv() 的许多有用参数，尤其是 decimal 来控制数值列中使用哪个十进制分隔符（通常为 '.' 或 ','）。破坏性变更：在此传递中包含的先前显式实现的 sep 参数，这意味着 sep 的默认值现在已从 ';' 更改为 pandas 的默认值，','。这是一个破坏性变更，但提高了与 pandas API 的一致性。

0.5.1 - 2018-08-28

更改

• 列元数据（目前基本上只是单位）现在存储在单独的字段中，而不是作为子数据帧列的monkeypatches。后者太脆弱了。

新增

• Table.df 设置器：用户现在可以替换Table的子数据帧，只要新的df的所有列都在（并且与）Table的列规范（名称：ColumnMetadata的字典）中描述。如果不是，将引发错误。
• PS-4 通过目的地获取 Bundle.tables() 的能力
• PS-13 向 Bundle.tables() 添加 exact_name 选项
• 列元数据现在不仅支持单位，还支持自由文本备注，但此功能目前尚未在文件读取器和写入器中使用；直到它被使用，此功能将不太有用。

修复

• PS-7 使用 read_excel() 后，除非手动重置DataFrame索引，否则 evaluate_expressions() 会失败
• 其他小错误修复。

0.5.0 - 2018-08-10

与早期0.1包相比进行了全面重新设计。API中存在重大更改。Pandas数据帧现在位于Table对象的核心。需要Python 3.6。