Open-Spending-Gobble 0.1.0

# Gobble

Gobble是[Open-Spending](next.openspending.org)的客户端API，Open-Spending是一个国际平台，用于打包、共享和可视化预算数据。Gobble的功能与[打包界面](next.openspending.org/packager)完全相同，只是以编程方式实现。它可以作为Python客户端或命令行界面使用。它与2.7、3.3、3.4和3.5版本兼容。您可以通过`pip`安装它。

```
pip install gobble
```

## 财政数据包

一个通用的[数据包](http://frictionlessdata.io/data-packages/)是一个轻量级的数据容器。一个[财政数据包](http://fiscal.dataprotocols.org/)是针对政府预算和支出数据的特殊类型数据包。它是面向用户的，旨在易于使用，无论是发布数据（例如政府）还是想要使用数据的人（如研究人员和记者）。

从技术上讲，财政数据包由一个指向数据文件的`JSON`描述符组成。`JSON`描述符需要遵循[fiscal数据规范](http://fiscal.dataprotocols.org/spec/)。一个基本的本地财政数据包可能看起来像这样

```
/basepath/budget.json
/data/budget_2014.csv
budget_2015.csv
```

一旦您的财政数据包准备就绪，您就可以开始使用Gobble了。

## 命令行界面

Asciinema 即将到来...

## Python 客户端

### 财务数据包对象

在 Gobble 中，财务数据通过 `FiscalDataPackage` 类表示。它是定义在 [datapackage-py](https://github.com/frictionlessdata/datapackage-py) 库中的 `DataPackage` 类的子类。要创建一个 `FiscalDataPackage` 对象，请将您的描述符路径传递给构造函数

```
budget = FiscalDataPackage('path/to/my/package/descriptor.json')
```

注意，截至今天，Open-Spending 仅支持 `CSV` 格式的数据文件，因此如果您尝试传递其他格式，`FiscalDataPackage` 将引发 `NotImplemented` 错误。

### 验证

要验证财务数据包描述符模式

```
bugdet.validate()
```

如果描述符模式无效，将引发 `ValidationError`。要获取 `list` 错误，请将 `raise_error` 标志设置为 `False`。
```
budget.validate(raise_error=False)
```

### 上传

要将财务数据包上传到 Open-Spending

```
url = budget.upload() # 在 Open-Spending 上的新包的 URL
```

默认情况下，上传的包是私有的。您可以像这样切换发布状态

```
new_state = budget.toggle('public') # 返回 'public'
```

### 搜索

您可以从 Open-Spending 平台这样搜索（并下载）现有财务数据包的描述符文件

```
query = {'countryCode': 'MX'}
results = search(query)
```

其中 `results` 是 `JSON` 包描述符的列表（作为 `dict`）。有效的搜索键是：`size`、`title`、`author`、`description`、`regionCode`、`countryCode`、`cityCode`。或者，您可以使用神奇的 `q` 键同时搜索所有字段。

您可以限制搜索结果并将您的私有包包含在结果中，如下所示

```
query = {'author': 'mickey_mouse'}
results = search(query, limit=5, private=True)
```

## 资源

- [Open-Spending 网络平台](next.openspending.org)
- [Open-Spending 开发者文档](http://docs.openspending.org/en/latest/)
- [datapackage-py 包存储库](http://frictionlessdata.io/data-packages/)
- [财务数据包主页](http://fiscal.dataprotocols.org/)
- [开放知识基金会](https://okfn.org)

## 许可证

Gobble 采用 [MIT 许可证](https://open-source.org.cn/licenses/MIT)。

## 贡献

我们欢迎反馈、问题和拉取请求。请查看 [贡献指南](https://github.com/okfn/coding-standards)。