数据源 Python 库

Google 开源了一个 Python 库，可创建 DataTable 对象供可视化图表使用。该库可用于在 Python 中创建 DataTable，并以下述三种格式之一输出：

  • JSON 字符串 - 如果您正在托管使用您数据的可视化图表的网页，可以生成一个 JSON 字符串并传递到 DataTable 构造函数中以进行填充。
  • JSON 响应 - 如果您未托管托管可视化图表的页面，只是想充当外部可视化图表的数据源，则可以创建可在响应数据请求时返回的完整 JSON 响应字符串。
  • JavaScript 字符串 - 您可以将数据表输出为包含几行 JavaScript 代码的字符串，这些代码将使用 Python 表中的数据创建并填充 google.visualization.DataTable 对象。然后，您可以在引擎中运行此 JavaScript，以生成并填充 google.visualization.DataTable 对象。这通常仅用于调试。

本文档假定您了解基本的 Python 编程，并且已阅读有关 创建可视化图表和使用可视化图表的简介文档。

点击此处可找到 Python 库。

目录

如何使用该库

下面更详细地介绍了基本步骤：

1. 创建 gviz_api.DataTable 对象

从上面的链接导入 gviz_api.py 库，并实例化 gviz_api.DataTable 类。该类接受两个参数：表架构（用于描述表中数据的格式）和要填充表的可选数据。您可以稍后根据需要添加数据，也可以完全覆盖数据，但不能移除个别行，或者清除表架构。

2. 描述表架构

表架构由传入构造函数中的 table_description 参数指定。一旦设置便无法再进行更改。该架构描述了表中的所有列：每列的数据类型、ID 和可选标签。

每一列都由一个元组进行描述：(ID [,data_type [,label [,custom_properties]]]]。

  • ID - 用于标识列的字符串 ID。可以包含空格。 每列的 ID 必须是唯一的。
  • data_type - [可选] 该列中数据的 Python 数据类型的字符串描述符。您可以在 SingleValueToJS() 方法中找到受支持数据类型的列表。例如“string”和“boolean”。 如果未指定，则默认为“string”。
  • label - 简单易懂的列名称，可能会作为可视化图表的一部分显示。如果未指定，则系统会使用 ID 值。
  • custom_properties - 自定义列属性的 {String:String} 字典。

表架构是列描述符元组的集合。每个列表成员、字典键或字典值都必须是另一个集合或描述符元组。您可以使用字典或列表的任意组合，但每个键、值或成员最终必须计算为描述符元组。以下是一些示例。

  • 列列表：[('a', 'number'), ('b', 'string')]
  • Dictionary of lists: {('a', 'number'): [('b', 'number'), ('c', 'string')]}
  • Dictionary of dictionaries: {('a', 'number'): {'b': 'number', 'c': 'string'}}
  • 依此类推，嵌套任意级别。

3. 填充数据

如需将数据添加到表中，请构建数据元素结构，采用与表架构完全相同的结构。因此，例如，如果您的架构是列表，则数据必须是列表：

  • schema: [("color", "string"), ("shape", "string")]
  • 数据：[["blue", "square"], ["red", "circle"]]

如果架构是一个字典，则数据必须是字典：

  • schema: {("rowname", "string"): [("color", "string"), ("shape", "string")] }
  • 数据：{"row1": ["blue", "square"], "row2": ["red", "circle"]}

表中的一行是相应数据和架构的一部分。例如，以下代码段展示了如何将一个由两列构成的列表的架构应用于两行数据。

Schema:[(color),(shape)]
            /     \       
Data: [["blue", "square"], ["red", "circle"]]

Table: 
      Color    Shape
      blue     square
      red      circle

请注意，此处的字典键的计算结果为列数据。您可以在代码的 AppendData() 方法文档中找到更复杂的示例。允许这种复杂嵌套的目的是让您能够使用适合自己需求的 Python 数据结构。

4. 输出数据

最常见的输出格式是 JSON，因此您可能会使用 ToJsonResponse() 函数来创建要返回的数据。但是，如果您解析输入请求并支持不同的输出格式，则可以调用任何其他输出方法以返回其他格式，包括逗号分隔值、制表符分隔值和 JavaScript。JavaScript 通常仅用于调试。请参阅实现数据源，了解如何处理请求以获得首选响应格式。

用法示例

以下是一些示例，展示了如何使用各种输出格式。

ToJSon 和 ToJS 示例

#!/usr/bin/python

import gviz_api

page_template = """
<html>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages:['table']});

    google.charts.setOnLoadCallback(drawTable);
    function drawTable() {
      %(jscode)s
      var jscode_table = new google.visualization.Table(document.getElementById('table_div_jscode'));
      jscode_table.draw(jscode_data, {showRowNumber: true});

      var json_table = new google.visualization.Table(document.getElementById('table_div_json'));
      var json_data = new google.visualization.DataTable(%(json)s, 0.6);
      json_table.draw(json_data, {showRowNumber: true});
    }
  </script>
  <body>
    <H1>Table created using ToJSCode</H1>
    <div id="table_div_jscode"></div>
    <H1>Table created using ToJSon</H1>
    <div id="table_div_json"></div>
  </body>
</html>
"""

def main():
  # Creating the data
  description = {"name": ("string", "Name"),
                 "salary": ("number", "Salary"),
                 "full_time": ("boolean", "Full Time Employee")}
  data = [{"name": "Mike", "salary": (10000, "$10,000"), "full_time": True},
          {"name": "Jim", "salary": (800, "$800"), "full_time": False},
          {"name": "Alice", "salary": (12500, "$12,500"), "full_time": True},
          {"name": "Bob", "salary": (7000, "$7,000"), "full_time": True}]

  # Loading it into gviz_api.DataTable
  data_table = gviz_api.DataTable(description)
  data_table.LoadData(data)

  # Create a JavaScript code string.
  jscode = data_table.ToJSCode("jscode_data",
                               columns_order=("name", "salary", "full_time"),
                               order_by="salary")
  # Create a JSON string.
  json = data_table.ToJSon(columns_order=("name", "salary", "full_time"),
                           order_by="salary")

  # Put the JS code and JSON string into the template.
  print "Content-type: text/html"
  print
  print page_template % vars()


if __name__ == '__main__':
  main()

ToJSonResponse 示例

JSonResponse 由远程客户端在数据请求中使用。

#!/usr/bin/python

import gviz_api

description = {"name": ("string", "Name"),
               "salary": ("number", "Salary"),
               "full_time": ("boolean", "Full Time Employee")}
data = [{"name": "Mike", "salary": (10000, "$10,000"), "full_time": True},
        {"name": "Jim", "salary": (800, "$800"), "full_time": False},
        {"name": "Alice", "salary": (12500, "$12,500"), "full_time": True},
        {"name": "Bob", "salary": (7000, "$7,000"), "full_time": True}]

data_table = gviz_api.DataTable(description)
data_table.LoadData(data)
print "Content-type: text/plain"
print
print data_table.ToJSonResponse(columns_order=("name", "salary", "full_time"),
                                order_by="salary")