csvw

此包提供

• 一个Python API，用于根据网络上的CSV规范读取和写入关系型、表格数据。
• 用于读取和验证CSVW数据的命令行工具。

链接

• GitHub: https://github.com/cldf/csvw
• PyPI: https://pypi.ac.cn/project/csvw
• 问题跟踪器: https://github.com/cldf/csvw/issues

安装

此包在Python >=3.8下运行，请使用pip进行安装

$ pip install csvw

命令行界面

csvw2json

将CSVW数据转换为JSON

$ csvw2json tests/fixtures/zipped-metadata.json 
{
    "tables": [
        {
            "url": "tests/fixtures/zipped.csv",
            "row": [
                {
                    "url": "tests/fixtures/zipped.csv#row=2",
                    "rownum": 1,
                    "describes": [
                        {
                            "ID": "abc",
                            "Value": "the value"
                        }
                    ]
                },
                {
                    "url": "tests/fixtures/zipped.csv#row=3",
                    "rownum": 2,
                    "describes": [
                        {
                            "ID": "cde",
                            "Value": "another one"
                        }
                    ]
                }
            ]
        }
    ]
}

csvwvalidate

验证CSVW数据

$ csvwvalidate tests/fixtures/zipped-metadata.json 
OK

csvwdescribe

使用CSVW元数据描述表格数据文件

$ csvwdescribe --delimiter "|" tests/fixtures/frictionless-data.csv
{
    "@context": "http://www.w3.org/ns/csvw",
    "dc:conformsTo": "data-package",
    "tables": [
        {
            "dialect": {
                "delimiter": "|"
            },
            "tableSchema": {
                "columns": [
                    {
                        "datatype": "string",
                        "name": "FK"
                    },
                    {
                        "datatype": "integer",
                        "name": "Year"
                    },
                    {
                        "datatype": "string",
                        "name": "Location name"
                    },
                    {
                        "datatype": "string",
                        "name": "Value"
                    },
                    {
                        "datatype": "string",
                        "name": "binary"
                    },
                    {
                        "datatype": "string",
                        "name": "anyURI"
                    },
                    {
                        "datatype": "string",
                        "name": "email"
                    },
                    {
                        "datatype": "string",
                        "name": "boolean"
                    },
                    {
                        "datatype": {
                            "dc:format": "application/json",
                            "base": "json"
                        },
                        "name": "array"
                    },
                    {
                        "datatype": {
                            "dc:format": "application/json",
                            "base": "json"
                        },
                        "name": "geojson"
                    }
                ]
            },
            "url": "tests/fixtures/frictionless-data.csv"
        }
    ]
}

Python API

在csvw.readthedocs.io/en/latest/找到Python API文档。

使用Python代码使用csvw的快速示例

import json
from csvw import CSVW
data = CSVW('https://raw.githubusercontent.com/cldf/csvw/master/tests/fixtures/test.tsv')
print(json.dumps(data.to_json(minimal=True), indent=4))
[
    {
        "province": "Hello",
        "territory": "world",
        "precinct": "1"
    }
]

已知限制

• 我们使用utf-8-sig编解码器读取指定为UTF-8编码的所有数据。因此，如果此类数据以U+FEFF开头，则将其解释为BOM并跳过。
• 低级CSV解析委托给Python标准库中的csv模块。因此，如果在Dialect实例中指定了commentPrefix，则会导致跳过以commentPrefix开头的第一行值，即使该值被引号引用。
• 此外，包含escapechar的单元格内容在指定最小引号时可能无法按预期往返（当指定escapechar或具有quoteChar但doubleQuote==False的csvw.Dialect时），这是由于Python版本间csv行为的不一致（参见https://bugs.python.org/issue44861）。

CSVW兼容性

虽然我们使用CSVW规范作为指南，但此包并未（并且可能永远不会）实现此规范的全部范围。

• 当读取带有标题的CSV文件时，列不是与tableSchema中的列描述顺序匹配，而是基于CSV列标题和列描述的name和titles属性进行匹配。这允许更多的灵活性，因为CSV文件中的列可以重新排序而不破坏元数据。可以通过在表的方言描述中指定"header": false和"skipRows": 1来强制执行更严格的匹配。

但是，csvw.CSVW对于以下内容正常工作：

• 269个JSON测试中的269个
• 282个验证测试中的280个
• 18个非规范性测试中的10个

来自CSVW测试套件。

与Frictionless Data规范的兼容性

CSVW描述的数据集基本上相当于包含所有数据资源的Frictionless DataPackage，其中所有数据资源都是表格数据。因此，csvw包提供了一些转换功能。要“从数据包读取CSVW数据”，有csvw.TableGroup.from_frictionless_datapackage方法

from csvw import TableGroup
tg = TableGroup.from_frictionless_datapackage('PATH/TO/datapackage.json')

然后可以将TableGroup序列化以转换元数据

tg.to_file('csvw-metadata.json')

请注意，CSVW元数据文件必须写入数据包的目录，以确保数据资源的工作相对路径。

此功能 - 与frictionless describe的架构推理功能相结合 - 为一组“原始”CSV文件提供了一种方便的方式来启动CSVW元数据，如上面描述的csvwdescribe命令所实现。

另请参阅

• https://www.w3.org/2013/csvw/wiki/Main_Page
• https://csvw.org
• https://github.com/CLARIAH/COW
• https://github.com/CLARIAH/ruminator
• https://github.com/bloomberg/pycsvw
• https://specs.frictionlessdata.io/table-schema/
• https://github.com/theodi/csvlint.rb
• https://github.com/ruby-rdf/rdf-tabular
• https://github.com/rdf-ext/rdf-parser-csvw
• https://github.com/Robsteranium/csvwr

许可证

本软件包采用Apache 2.0许可证进行分发。