流读写表格数据的一致接口(csv/xls/json/etc)
tabulator的Python项目详细描述
制表符py
用于读取和写入表格数据的库(csv/xls/json/etc)。
功能
- 支持最常见的表格格式:csv、xls、ods、json、google sheets、sql和其他格式。请参见下面的完整列表
- 加载本地和远程数据:支持http和ftp。
- 内存使用率低:只有当前行保留在内存中,因此您可以 大型数据集。
- 支持压缩文件:使用ZIP或GZIP算法。
- 可扩展性:您可以添加对自定义文件格式和加载程序的支持(例如 FTP)
内容
开始
安装
$ pip install tabulator
在cli上运行
tabulator附带一个名为tabulator
的简单cli来读取表格数据。为了
例子:
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人
通过运行tabulator--help
在python上运行
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]
您可以在示例目录中找到其他示例。
文档
在下面的小节中,我们将介绍 这个图书馆。所有的例子都是用Python3.6测试的,但是应该 使用python 3.3+运行良好。
流
流
类表示表格流。它将文件路径作为
源
参数。例如:
<scheme>://path/to/file.<format>
它使用此路径来确定文件格式(例如csv或xls)和方案
(如http或postgresql)。它还支持从http://example.com?format=csv
。如有必要,您还可以显式定义它们。
我们试试吧。首先,我们创建一个流
对象,将路径传递给csv文件。
importtabulatorstream=tabulator.Stream('data.csv')
此时,文件尚未读取。让我们打开小溪,这样我们就可以 阅读内容。
try:stream.open()excepttabulator.TabulatorExceptionase:pass# Handle exception
这将打开底层数据流,读取一个小样本来检测
文件编码,并准备要读取的数据。我们捉到
制表器。制表异常
这里,以防出错。
我们现在可以读取文件内容了。要遍历每一行,我们需要:
forrowinstream.iter():print(row)# [value1, value2, ...]
stream.iter()
方法将以值列表的形式返回每一行数据。如果
如果愿意,可以调用stream.iter(keyed=true),它返回
以列名为键的字典。不管怎样,这种方法只保留一个
一次只存储一行。这意味着它可以处理大文件
不会占用太多内存。
如果要读取整个文件,请使用stream.read()
。它接受同样的
参数为stream.iter(),但同时返回所有行。
stream.reset()rows=stream.read()
注意,我们在读取行之前调用了stream.reset()。这是因为 在内部,制表器只保留指向文件中当前位置的指针。 如果我们不重置这个指针,我们将从停止的地方开始读取。 例如,如果我们再次运行stream.read(),将得到一个空列表,如 内部文件指针位于文件末尾(因为我们已经读取了 这一切)。根据文件位置,可能需要下载 再次倒带文件(例如,从Web加载文件时)。
完成后,使用以下命令关闭流:
stream.close()
整个示例如下:
$ pip install tabulator0
它可以重写为使用python的上下文管理器接口:
$ pip install tabulator1
这是首选d方式,因为python会自动关闭流,即使一路上抛出了一些异常。
完整的api文档可以作为docstrings在流源代码中获得。
标题
默认情况下,制表器认为所有文件行都是值(即没有 标头)
$ pip install tabulator2
若有标题行,可以将headers
参数用于其行
数字(从1开始)。
$ pip install tabulator3
您还可以传递字符串列表以显式定义标题:
$ pip install tabulator4
制表器还支持xls
和xlsx
格式的多行标题。
$ pip install tabulator5
编码
您可以通过编码指定文件编码(例如
utf-8
和latin1
)。
参数。
$ pip install tabulator6
如果未设置此参数,制表符将尝试从数据中推断它。如果你
加载文件时,获取unicodedecodeerror
,尝试将编码设置为
UTF-8
压缩(仅限python3)
制表器同时支持ZIP和GZIP压缩方法。默认情况下,它将从文件名推断:
$ pip install tabulator7
您也可以显式设置:
$ pip install tabulator8
选项
- 文件名:要处理的zip文件中的文件名(默认为第一个文件)
允许HTML
流
类在检测到html时引发tabulator.exceptions.formaterror
内容。这有助于避免试图加载
HTML页面内的CSV文件,例如在GitHub上。
您可以使用允许HTML
选项禁用此行为:
$ pip install tabulator9
样本量
检测文件头并运行其他检查,如验证文件
不包含HTML,制表符读取stream.open()上的行样本
方法。此数据可通过
stream.sample
属性获得。数量
使用的行可以通过样本大小
参数定义(默认为100)。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人0
您可以通过将sample_size
设置为零来禁用此功能。这样,就不会有数据了
继续阅读stream.open()
字节样本大小
制表器需要读取文件的一部分以推断其编码。这个
bytes\u sample\u size
参数控制将为此读取多少字节
检测(默认为10000)。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人1
您可以通过将bytes\u sample\u size
设置为零来禁用此功能,在这种情况下
使用机器区域设置的默认编码。
忽略空白标题
当true
时,制表符将忽略具有空标题的列(默认为
错误
)。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人2
强制字符串
当true
时,所有行的值都将转换为字符串(默认为
错误
)。无
值将转换为空字符串。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人3
强制分析
当true
时,在分析格式错误的行时不引发异常,而只是
返回空行。否则,制表器将
制表符.exceptions.sourceerror
无法分析行时。默认为false
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人4
跳过行
要跳过的行号和/或字符串的列表。 如果是字符串,则将跳过以它开头的所有行(例如""和"//")。 如果是空字符串,则将跳过以空列开头的所有行。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人5
如果headers
参数也设置为整数,则它将使用第一个未跳过的行作为头。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人6
分析后
分析行后可以筛选或转换行的函数列表。这些 函数接收包含行号、标题的扩展行 列表和行值列表。然后他们处理这些行,并放弃或丢弃 无论是否修改。
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人7
这些函数按顺序应用,作为一个简单的daTA管道。在这个例子中
在上面,乘2
只看到由跳过奇数行生成的行
键控和扩展行
方法stream.iter()和stream.read()接受键控的
扩展
标记参数以修改返回行的方式。
默认情况下,每一行作为其单元格值的列表返回:
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人8
当keyed=true
时,行作为字典返回,将列名映射到行中的值:
$ tabulator https://github.com/frictionlessdata/tabulator-py/raw/4c1b3943ac98be87b551d87a777d0f7ca4904701/data/table.csv.gz id,name 1,english 2,中国人9
当extended=true
时,行作为的元组返回(行号、标题、行)
,其中行号
是当前行号(从1开始)。
headers
是带有标题名称的列表,而row
是带有行的列表
值:
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]0
支持的方案
文件
默认方案,本地文件系统中的一个文件。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]1
http/https/ftp/ftps
< Buff行情>在Python2中,制表符
由于底层库中的限制,无法流式传输远程数据源。整个数据源将加载到内存中。在python 3中没有这样的问题,远程文件是流式传输的。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]2
选项
- HTTP会话-a
请求.会话
对象。请阅读请求文档中的更多信息 - http_stream-尽可能启用或禁用http streaming(默认启用)。如果要将整个文件预加载到内存中,请禁用它。
流
源是一个类似python的文件对象。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]3
文本
源是包含表格数据的字符串。方案和格式 必须明确设置,因为无法推断。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]4
支持的文件格式
在本节中,我们将描述支持的文件格式,以及它们各自的 配置选项和操作。有些格式只支持读取操作, 而另一些则同时支持读和写。
csv(读写)
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]5
选项
它支持python csv库中的所有选项。检查其 文档了解更多信息。
xls/xlsx(只读)
< Buff行情>制表器无法传输xls
文件,因此整个文件加载到
记忆。xlsx
文件支持流媒体。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]6
选项
- 工作表:工作表名称或编号(从1开始)
- 填充合并单元格:如果
true
它将取消合并并填充所有合并单元格 可见值。启用此选项后,解析器无法传输数据和 将整个文档加载到内存中。 - 保留格式:如果
true
它将尝试保留数值和时间单元格的文本格式,这些单元格将根据其在电子表格(experimetal)中的外观返回字符串形式
ODS(只读)
< Buff行情>默认情况下,此格式不包含在包中。要使用它,请安装带有附加功能的制表程序:$pip install tabulator[ods]
源文件应该是有效的开放式办公文档。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]7
选项
- 工作表:工作表名称或编号(从1开始)
gsheet(只读)
一个可公开访问的谷歌电子表格。
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]8
sql(只读)
sqlalchemy支持的任何数据库url
fromtabulatorimportStreamwithStream('data.csv',headers=1)asstream:stream.headers# [header1, header2, ..]forrowinstream:print(row)# [value1, value2, ..]9
选项
- 表(必需):数据库表名
- 排序方式:行排序的SQL表达式(例如
名称描述
)
数据包(只读)
< Buff行情>默认情况下,此格式不包含在包中。你可以通过
使用pip安装制表程序[datapackage]
a表格数据包
<scheme>://path/to/file.<format>
0
选项
- 资源:资源名称或索引(从0开始)
内联(只读)
列表列表,或将列名映射到 各自的值。
<scheme>://path/to/file.<format>
1
json(只读)
包含列表列表或映射列的dict列表的json文档
名称到各自的值(请参见inline
格式以获取示例)。
<scheme>://path/to/file.<format>
2
选项
- 属性:包含表格数据的属性的json路径。例如,考虑到json
{"response":{"data":[…]}
,应该将属性
设置为response.data
ndjson(只读)
<scheme>://path/to/file.<format>
3
TSV(只读)
<scheme>://path/to/file.<format>
4
添加对新文件源、格式和写入程序的支持
制表器的编写考虑到了可扩展性,允许您添加对 新的表格文件格式、方案(例如ssh)和编写器(例如mongodb)。那里 有三个组件可以做到这一点:
-
LI>装载机
- 从某个位置加载流(例如ssh)
- 以某种格式(例如XLS)分析表格数据流
- 将表格数据写入某个目标(例如MongoDB)
在本节中,我们将了解如何编写自定义类来扩展这些组件。
定制装载机
您可以通过创建自定义加载程序来添加对新方案(例如ssh)的支持。
自定义加载程序是通过继承loader
类实现的,并且
实施其方法。然后stream
可以使用此加载程序加载数据
通过自定义加载程序={'scheme':customloader}
参数传递它。
自定义加载程序的框架如下:
<scheme>://path/to/file.<format>
5
通过查看
制表机、装载机
模块。
自定义分析器
您可以通过创建自定义解析器来添加对新文件格式的支持。同样地
对于自定义加载程序,通过从
解析器
类,并实现其方法。这个解析器可以被
stream
通过自定义解析器={'format':customparser}
参数传递数据来解析数据。
自定义解析器的框架如下:
<scheme>://path/to/file.<format>
6
通过查看
制表器。分析器
模块。
自定义写入程序
您可以通过创建自定义的
作家。自定义写入程序是通过从基写入程序继承来实现的。
类,并实现其方法。然后stream
可以使用此writer
通过custom writers={'format':customwriter}
参数写入数据。
自定义编写器的框架如下:
<scheme>://path/to/file.<format>
7
通过查看
制表器。写入器
模块。
验证
您可以使用validate
函数检查制表器是否可以加载源。
<scheme>://path/to/file.<format>
8
例外情况
制表符引发的所有异常都继承自
tabulator.exceptions.tabulatorexception
,因此可以使用它来捕获
任何制表异常。您可以了解
查看ns.py" rel="nofollow"title="制表符异常">制表符异常模块。
API参考
api引用在制表器类中作为docstring写入。好的 开始的地方是流类,它管理所有 加载和分析数据文件。
贡献
本项目遵循开放知识国际编码标准。
我们建议您使用virtualenv
将此项目与
机器中的软件包。
要安装项目及其开发依赖项,请运行:
<scheme>://path/to/file.<format>
9
要运行测试,请使用:
importtabulatorstream=tabulator.Stream('data.csv')0
更改日志
这里只描述了打破和最重要的变化。所有发布版本的完整变更日志和文档都可以在格式良好的提交历史记录中找到。
v1.24
- 增加了对压缩类文件对象的支持
v1.23
- 为
stream.headers
属性添加了setter
v1.22
- 如果提供了
skip_rows
参数,并且数据源顶部有注释(请参见264),那么headers
参数现在将使用第一个未跳过的行
v1.21
- 为xlsx实现了实验性的
保留格式
v1.20
- 添加了对在zip源中指定文件名的支持
v1.19
更新行为:
- 对于
ods
格式,现在检测到布尔、整数和datatime本机类型
v1.18
更新行为:
- 对于
xls
格式,现在检测到布尔、整数和数据时间本机类型
v1.17
更新行为:
- 增加了对Python3.7的支持
v1.16
添加了新的API:
跳过行
支持空字符串跳过第一列为空的行
v1.15
添加了新的API:
- 格式将从
http://example.com这样的url中提取?format=csv
v1.14
更新行为:
- 现在
xls
booleans将被解析为booleans而不是integer
v1.13
添加了新的API:
skip_rows
参数现在支持从末尾开始跳过行的负数
v1.12
更新行为:
- 如果无法识别选项,将发出
用户警告
警告,而不是引发异常。
v1.11
添加了新的API:
- 添加了
http/https
格式的http会话
参数(它现在使用请求
) - 添加了对多行标题的支持:
标题
参数接受范围,如[1,3]
v1.10
添加了新的API:
- 增加了对压缩文件的支持,例如python3上的
zip
和gz
流
构造函数现在接受压缩
参数http/https
方案现在接受一个http\u流
标志
v1.9
改进的行为:
headers
参数允许设置键控源和cherry pick值的顺序
v1.8
添加了新的API:
- formats
xls/xlsx/ods
支持通过sheet
参数传递的工作表名称 流
构造函数接受忽略空白的头
选项
v1.7
改进的行为:
- 重新定位
datapackage
format ondatapackage@1
library
v1.6
添加了新的API:
- 参数<代码>stream构造函数的source可以是pathlib.path
v1.5
添加了新的API:
- 参数
bytes\u sample\u size
用于流
构造函数
v1.4
改进的行为:
- 将编码名称更新为规范格式
v1.3
添加了新的API:
stream.scheme
流格式
流编码
将临时api提升为稳定api:
加载程序
(自定义加载程序)分析器
(自定义分析器)写入程序
(自定义写入程序)验证
v1.2
改进的行为:
- 自动检测常用CSV分隔符
v1.1
添加了新的API:
- 在
xls/xlsx
格式中添加了填充合并单元格的选项
v1.0
添加了新的API:
- 已发布
loader/parser/writer
api - 添加了
流
参数强制字符串
- 添加了
stream
参数force\u parse
- 添加了
流
参数自定义写入程序
不推荐的API删除:
- 删除了
topen
和表
-改用流
。 - 删除了
stream
参数加载程序/分析器选项
-改用**选项
临时API已更改:
- 更新了
loader/parser/writer
api-请使用更新版本
v0.15
添加了临时API:
- 非官方支持
流
参数自定义加载程序/分析器