使用specs.friectionlessdata.io中定义的数据包的实用程序
datapackage的Python项目详细描述
数据包py
<
用于处理数据包的库。
功能
包用于处理数据包的类资源用于处理数据资源的类配置文件使用配置文件的类验证用于验证数据包描述符的函数inferer用于推断数据包描述符的函数
内容
开始
安装
包使用语义版本控制。这意味着主要版本可能包括破坏性更改。强烈建议在设置/要求文件中指定数据包版本范围，例如数据包
$ pip install datapackage
OSX 10.14+
如果在Mac OSX 10.14（mojave）或更高版本上安装数据包时收到有关cchardet包的错误，请执行以下步骤：
- 在终端中运行以下命令，确保您拥有最新的X代码：
xcode select--install - 然后转到https://developer.apple.com/download/more/" rel="nofollow">https://developer.apple.com/download/more/并下载
命令行工具。注意，这需要一个Apple ID。 - 然后，在终端中运行
open/library/developer/commandlinetools/packages/macos-sdk-headers\u for\u macos-10.14.pkg您可以在本文中阅读有关这些步骤的更多信息。
示例
本自述中的代码示例需要Python3.3+解释器。您可以在示例目录中看到更多示例。
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()
文档
包装
用于处理数据包的类。它提供多种功能，如加载本地或远程数据包、推断数据包描述符、保存数据包描述符等。
假设我们在data目录中有一些本地csv文件。让我们使用包创建基于此数据的数据包类：
data/cities.csv
city,location london,"51.50,-0.11" paris,"48.85,2.30" rome,"41.89,12.51"< Buff行情>
data/population.csv
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,2860000
首先，我们创建一个空白数据包：
package=Package()
现在我们准备好根据已有的数据文件推断数据包描述符。因为我们有两个csv文件，所以我们使用glob模式**/*.csv：
package.infer('**/*.csv')package.descriptor#{ profile: 'tabular-data-package',# resources:# [ { path: 'data/cities.csv',# profile: 'tabular-data-resource',# encoding: 'utf-8',# name: 'cities',# format: 'csv',# mediatype: 'text/csv',# schema: [Object] },# { path: 'data/population.csv',# profile: 'tabular-data-resource',# encoding: 'utf-8',# name: 'population',# format: 'csv',# mediatype: 'text/csv',# schema: [Object] } ] }
infer方法找到了我们所有的文件，并对其进行了检查，以提取有用的元数据，如profile、encoding、format、table schema等。让我们稍微调整一下：
package.descriptor['resources'][1]['schema']['fields'][1]['type']='year'package.commit()package.valid# true
因为我们的资源是表格式的，所以我们可以将其作为表格式数据来读取：
package.get_resource('population').read(keyed=True)#[ { city: 'london', year: 2017, population: 8780000 },# { city: 'paris', year: 2017, population: 2240000 },# { city: 'rome', year: 2017, population: 2860000 } ]
让我们将描述符保存为zip文件：
package.save('datapackage.zip')
要继续使用数据包，我们只需再次加载它，但这次使用localdata package.zip：
$ pip install datapackage0
这只是包类的基本介绍。要了解更多信息，让我们看看包类api参考资料。
包（描述符=无，基路径=无，严格=假，存储=无，**选项）
要实例化包的构造函数类。
描述符（str/dict）-作为本地路径、url或对象的数据包描述符基本路径（str）-所有相对路径的基本路径strict（bool）-用于更改验证行为的strict标志。将其设置为true将导致对任何具有无效描述符的操作抛出错误存储（str/tableschema.storage）-存储名称，如sql或存储实例选项（dict）-用于创建存储的存储选项（exceptions.datapackageexception）-如果出现错误，则引发错误（包）-返回数据包类实例
包。有效
（bool）-返回验证状态。在严格模式下总是正确的。
包。错误
（异常[]）-返回验证错误。在严格模式下总是空的。
包.配置文件
（profile）-返回profile类的实例（见下文）。
包.描述符
（dict）-返回数据包描述符
包.基本路径
（str/none）-返回数据包基本路径
包.资源
（resource[]）-返回一组资源实例（见下文）。
包.资源名称
（str[]）-返回资源名称数组。
包。获取资源（名称）
按名称获取数据包资源。
名称（str）-数据资源名称（resource/none）-返回资源实例，如果找不到则返回空值
包。添加资源（描述符）
将新资源添加到数据包。数据包描述符将使用新添加的资源描述符进行验证。
描述符（dict）-数据资源描述符（异常.datapackageexception）-如果出现错误，则引发错误（resource/none）-返回added资源实例，如果未添加则返回空值
包。删除资源（名称）
按名称删除数据包资源。删除资源描述符后，将验证数据包描述符。
名称（str）-数据资源名称（exceptions.datapackageexception）-如果出现错误，则引发错误（resource/none）-返回removedresource实例，如果找不到则返回null
包。获取组（名称）
按名称返回一组表格资源。有关组的详细信息，请参见组。
名称（str）-一组资源的名称（exceptions.datapackageexception）-如果出现错误，则引发错误（group/none）-返回一个组实例，如果找不到则返回空值
package.infer（pattern=false）
< Buff行情>参数模式仅适用于本地文件
推断数据包元数据。如果未提供模式，则仅推断现有资源（添加了编码、配置文件等元数据）。如果pattern被提供了新的资源，其中包含与模式匹配的文件名，则将添加并推断该资源。它提交对数据包实例的更改。
模式（str）-新资源的全局模式（dict）-返回数据包描述符
包提交（strict=none）
如果描述符中存在更改，请更新数据包实例。
strict（bool）-alterstrict下一步工作模式（exceptions.datapackageexception）-如果出现错误，则引发错误（bool）-成功时返回true，未修改时返回false
$ pip install datapackage1
包.保存（目标=无，存储=无，合并组=假，**选项）
如果传递了storage参数，则将此数据包保存到存储；如果target参数以.json结尾，则将此数据包的描述符保存到json文件；否则，将此数据包保存到zip文件。
target（string/file like）-将此数据包的内容保存到的文件路径或类文件对象。存储（str/tableschema.storage）-存储名称，如sql或存储实例合并组（bool）-如果提供了存储，请将组的所有表格资源保存到一个bucket中（例如保存到一个sql表中）。阅读更多关于组的信息选项（dict）-用于创建存储的存储选项（exceptions.datapackageexception）-如果写入包时出现错误，则引发（bool）-成功时返回true
它使用此数据包及其资源的内容将zip文件创建到文件或路径中。内容位于本地文件系统中的每个资源都将被复制到zip文件中。考虑以下数据包描述符：
$ pip install datapackage2
zip文件的最终结构为：
$ pip install datapackage3
其中datapackage.json的内容与返回的datapackage.descriptor相同。资源的文件名是根据其名称和格式字段（如果存在）生成的。如果资源没有名称，则将使用resource-x，其中x是资源列表中资源的索引（从零开始）。如果资源具有格式，则它将小写并附加到e名称，变为"名称.格式"
资源
用于处理数据资源的类。您可以使用iter/read方法读取或迭代表格资源，并使用row-iter/row-read方法以字节形式读取所有资源。
假设我们有一些本地csv文件。它可以是内联数据或远程链接-都由resource类支持（当然，在浏览器中使用的本地文件除外）。但假设现在是data.csv
$ pip install datapackage4
让我们创建并阅读一个资源。由于资源是表格式的，我们可以使用resource.read方法和键控选项来获取键控行数组：
$ pip install datapackage5
我们可以看到我们的位置只是一条线。但应该是地质点。罗马的位置也不可用，但它也只是一个n/a字符串，而不是pythonnone。首先，我们必须推断资源元数据：
$ pip install datapackage6
让我们修复不可用的位置。表架构规范中有一个missingValues属性。作为第一次尝试，我们在resource.descriptor.schema中将missingValues设置为n/a。可以就地更改资源描述符，但所有更改都应由resource.commit（）提交：：
$ pip install datapackage7
作为一个好的公民，我们决定检查资源描述符的有效性。这是无效的！我们应该为missingValues属性使用数组。也不要忘记将空字符串作为缺少的值：
$ pip install datapackage8
一切都好。看来我们已经准备好再次读取数据：
$ pip install datapackage9
现在我们看到：
- 位置是带有数字格和经度的数组
- 罗马的位置是本地javascript
null
由于数据读取没有错误，我们可以确保我们的数据在模式中是有效的。让我们保存资源描述符：
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()0
让我们检查一下新包装的dataresource.json。它包含到我们的数据文件的路径、推断的元数据和我们的missingValuestweak:
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()1
如果我们决定进一步改进它，我们可以更新dataresource.json文件，然后使用本地文件名再次打开它：
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()2
这只是对资源类的基本介绍。要了解更多信息，让我们看看资源类api引用。
资源（描述符={}，基路径=无，严格=假，存储=无，**选项）
要实例化资源的构造函数类。
描述符（str/dict）-作为本地路径、url或对象的数据资源描述符基本路径（str）-所有相对路径的基本路径strict（bool）-用于更改验证行为的strict标志。将其设置为true将导致对任何具有无效描述符的操作抛出错误存储（str/tableschema.storage）-存储名称，如sql或存储实例选项（dict）-用于创建存储的存储选项（exceptions.datapackageexception）-如果出现错误，则引发错误（资源）-返回资源类实例
资源。有效
（bool）-返回验证状态。在严格模式下总是正确的。
资源.错误
（异常[]）-返回验证错误。在严格模式下总是空的。
资源配置文件
（profile）-返回profile类的实例（见下文）。
资源描述符
- （dict）-返回资源描述符
资源名称
（str）-返回资源名
资源.内联
- < < >代码>（bool）-如果资源是内联的，则返回true
资源.本地
（bool）-如果资源是本地的，则返回true
资源.远程
（bool）-如果资源是远程的，则返回true
资源.多部分
（bool）-如果资源是多部分的，则返回true
资源表
（bool）-如果资源是表格式的，则返回true
资源.source
（list/str）-返回数据或路径属性
结合resource.source和resource.inline/local/remote/multipart提供了处理资源数据的可预测接口。
资源标题
< Buff行情>仅适用于表格资源（必须先开始读取，否则将返回none）
（str[]）-返回数据源头
资源.架构
< Buff行情>仅适用于表格资源
对于表格资源，它返回schema实例以与数据模式交互。阅读API文档-tableschema.schema
（tableschema.schema）-返回模式类实例
resource.iter（keyed=false，extended=false，cast=true，relations=false）
< Buff行情>仅适用于表格资源
iter通过表数据并根据表架构（async for loop）发出行转换。可以禁用数据广播。
键控（bool）-iter键控行扩展（bool）-iter扩展行强制转换（bool）-如果为false，则禁用数据强制转换关系（bool）-如果选择真外键字段，则将其解析为引用（exceptions.datapackageexception）-引发此进程中发生的任何错误（any[]/any{}）-生成行：[value1，value2]-base{header1:value1，header2:value2}-keyed[行号，[header1，header2]，[value1，value2]]-扩展
资源读取（keyed=false，extended=false，cast=true，relations=false，limit=none）
< Buff行情>仅适用于表格资源
读取整个表并以行数组的形式返回。行数可以限制。
键控（bool）-发出键控行的标志扩展（bool）-发出扩展行的标志强制转换（bool）-如果为false，则禁用数据强制转换的标志关系（bool）-如果选择真外键字段，则将其解析为引用限制（int）-要返回的行的整数限制（exceptions.datapackageexception）-引发此进程中发生的任何错误（list[]）-返回行数组（请参见table.iter）
资源.检查关系（）
< Buff行情>仅适用于表格资源
它检查外键并在存在完整性问题时引发异常。
（exceptions.relationerror）-如果存在完整性问题，则引发（bool）-如果没有问题，则返回true
资源.原始项（流=假）
以字节的形式遍历数据块。如果stream为真，则将返回类似文件的对象。
流（bool）-将返回类似文件的对象（bytes[]/filelike）-返回bytes[]/filelike
资源.raw_read（）
返回资源数据作为字节。
- （字节）-返回以字节为单位的资源数据
resource.infer（**选项）
推断资源元数据，如名称、格式、媒体类型、编码、架构和配置文件。它将这些更改提交到资源实例中。
选项-选项将传递到表模式.推断调用，以便对结果进行更多控制（例如，设置限制，置信度等）。（dict）-返回资源描述符
资源提交（strict=none）
如果描述符中有更改，请更新资源实例。
strict（bool）-alterstrict下一步工作模式（exceptions.datapackageexception）-如果出现错误，则引发错误（bool）-成功时返回true，未修改时返回false
资源.保存（目标，存储=无，**选项）
如果传递了storage参数，则将此资源保存到存储中，否则将此资源的描述符保存到json文件中。
目标（str）-保存资源的路径存储（str/tableschema.storage）-存储名称，如sql或存储实例选项（dict）-用于创建存储的存储选项（exceptions.datapackageexception）-如果出现错误，则引发错误（bool）-成功时返回true
组
表示一组表格资源的类。可以使用组将多个资源作为一个资源读取，或者将它们导出到数据库（例如，作为一个表）。要定义组，请将组：<；名称>；字段添加到相应的资源中。组的元数据将从"leading"资源的元数据（组名为的第一个资源）创建。
假设我们有一个数据包，其中两个表按一年划分，一个共享模式单独存储：
< Buff行情>CARS-2017.csv
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()3 < Buff行情>
CARS-2018.csv
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()4 < Buff行情>
cars.schema.json
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()5 < Buff行情>
datapackage.json
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()6
让我们单独阅读资源：
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()7
另一方面，这些资源由group:cars字段定义。这意味着我们可以将他们视为一个整体：
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()8
当我们需要将数据包保存到存储器（例如，SQL数据库）时，可以使用这种方法。有合并组标志可启用分组行为：
fromdatapackageimportPackagepackage=Package('datapackage.json')package.get_resource('resource').read()9
组
这个类没有任何公共构造函数。使用包。获取组
组名
（str）-返回组名
组标题
与 与 与resource.iter相同
与 表示来自profiles registry的json模式配置文件的组件
要实例化配置文件的构造函数 根据配置文件验证数据包 用于验证数据包描述符的独立函数： 验证数据包描述符。 用于推断数据包描述符的独立函数。 参数 推断数据包描述符。 库支持表模式规范中描述的外键。这意味着，如果数据包描述符对某些资源使用 假设我们有一个数据包： 让我们检查 我们可以看到有一个外键违规。这是因为我们的查找表resource.headers相同
组.架构resource.schema相同
类。组.iter（…）组。读取（…）资源相同。读取剖面图
city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
0
配置文件（配置文件）配置文件（str）-注册表中的配置文件名或json模式的url
（exceptions.datapackageexception）-如果出现错误，则引发错误（profile）-返回profile类实例
配置文件名（str/none）-返回配置文件名（如果可用）
配置文件.jsonschema（dict）。-返回profile json模式内容配置文件.验证（描述符）描述符。描述符（dict）-检索和取消引用的数据包描述符（exceptions.validationerror）-如果无效则引发
（bool）-如果有效，则返回true
验证
city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
1
验证（描述符）描述符（str/dict）-包描述符（其中之一）：
（bool）-有效时返回true
推断
city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
2
< Buff行情>推断（模式，基本路径=无）模式仅适用于本地文件模式（str）-全局文件模式
（dict）-返回数据包描述符
外键
resources[].schema.foreignkeys属性，则在读取操作时将检查数据完整性。city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
3
团队的关系资源：city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
4
cities没有慕尼黑的城市，但是我们有一个团队。我们需要在城市资源：city,location
london,"51.50,-0.11"
paris,"48.85,2.30"
rome,"41.89,12.51"
5
固定！但不仅有检查操作可用。我们可以使用relations参数对resource.iter/read方法取消引用资源关系：
city,location london,"51.50,-0.11" paris,"48.85,2.30" rome,"41.89,12.51"6
我们有一本包含城市数据的字典，而不是简单的城市名称。这些resource.iter/read方法将失败，其结果与resource相同。如果存在完整性问题，请检查u relationserror。但前提是传递了relations=true标志。
例外情况
异常。数据包异常
所有库异常的基类。如果有多个错误，可以从异常对象中读取：
city,location london,"51.50,-0.11" paris,"48.85,2.30" rome,"41.89,12.51"7
异常。加载错误
所有加载错误。
异常.validationerror
所有验证错误。
异常。casterror
所有值转换错误。
异常。关系错误
所有完整性错误。
异常。存储错误
所有存储错误。
CLI
< Buff行情>这是临时的原料药。如果您将其用作其他程序的一部分，请将具体的datapackage版本固定到您的需求文件中。
库附带一个简单的cli:
city,location london,"51.50,-0.11" paris,"48.85,2.30" rome,"41.89,12.51"8
$datapackage
city,location london,"51.50,-0.11" paris,"48.85,2.30" rome,"41.89,12.51"9
注释
在代理服务器后访问数据
在package=package（"https://xxx.json"）调用之前，请设置以下环境变量：
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,28600000
贡献
该项目遵循开放知识国际编码标准。
建议的入门方法是创建和激活项目虚拟环境。 要将包和开发依赖项安装到活动环境中，请执行以下操作：
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,28600001
要使用绒布和覆盖率运行测试：
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,28600002
对于linting，使用在pylama.ini中配置的pylama。在TH上舞台上已经有了 安装到您的环境中，可以与更细粒度的控件分开使用 如文档中所述-https://pylama.readthedocs.io/en/latest/
例如，按错误类型对结果排序：
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,28600003
使用tox.ini中配置的测试tox。
它已经安装到您的环境中，可以与文档中描述的更细粒度的控制一起单独使用-https://testrun.org/tox/latest/
例如，根据python 2环境检查测试子集，增加了详细程度。
--之后的所有位置参数和选项都将传递到py.test：
city,year,population london,2017,8780000 paris,2017,2240000 rome,2017,28600004
引擎盖下的tox使用pytest在pytest.ini中配置的
以及模拟包。此软件包仅在TOX环境下可用。
以下是库贡献者的列表：
- tryggvi bjórgvinssontryggvi.bjorgvinsson@okfn.org
- gunnlaugur thor briem gunnlaugur@gmail.com">gunnlaugur@gmail.com
- edouardedou4rd@gmail.com
- 迈克尔·鲍尔mihi@lo-res.org
- alex chandelalexchandel@gmail.com
- 杰西卡·B·哈姆里克
- 里卡多·拉富恩特
- 保罗沃尔什paulywalsh@gmail.com
- luiz armestoluiz.armesto@gmail.com
- hanslhansl@edge net
- femto traderfemto.trader@gmail.com
- vitor baptistavitor@vitorbaptista.com
- bryon jacobbryon@data.world
更改日志
这里只描述了打破和最重要的变化。所有发布版本的完整变更日志和文档都可以在格式良好的提交历史记录中找到。
v1.8
- 增加了对资源组的支持
v1.7
- 增加了对资源压缩的支持
v1.6
- 添加了对自定义请求会话的支持
v1.5
更新行为：
- 增加了对Python3.7的支持
v1.4
添加了新的API:
- 向资源描述符添加了
跳过行支持
v1.3
添加了新的API:
- property
package.base_path现在是公共可用的
v1.2
更新行为：
- cli命令现在只输出json格式的数据包描述符。
v1.1
添加了新的API:
- 添加了
package/resource与tableschema.storage-https://github.com/friectionlessdata/tableschema py storage之间的集成。它允许从不同的存储（如sql/bigquery/etc）加载和保存数据包。
欢迎加入QQ群-->： 979659372
