Biblioteca Python da fonte de dados

O Google abriu o código de uma biblioteca Python que cria objetos DataTable para consumo por visualizações. Essa biblioteca pode ser usada para criar um DataTable em Python e gerar a saída em qualquer um dos três formatos:

  • String JSON: se você estiver hospedando a página que hospeda a visualização que usa seus dados, poderá gerar uma string JSON para transmitir em um construtor DataTable para preenchê-la.
  • Resposta JSON: se você não hospedar a página que hospeda a visualização e só quiser atuar como uma fonte de dados de visualizações externas, poderá criar uma string de resposta JSON completa que poderá ser retornada em resposta a uma solicitação de dados.
  • String JavaScript: é possível gerar a tabela de dados como uma string que consiste em várias linhas de código JavaScript que criarão e preencherão um objeto google.visualization.DataTable com os dados da tabela Python. Em seguida, é possível executar esse JavaScript em um mecanismo para gerar e preencher o objeto google.visualization.DataTable. Normalmente, essa opção é usada apenas para depuração.

Presumimos que você entenda a programação Python básica e leia a documentação de introdução para criar uma visualização e usar uma visualização.

A biblioteca do Python está disponível aqui.

Índice

Como usar a biblioteca

Veja as etapas básicas em mais detalhes:

1. Criar um objeto gviz_api.DataTable

Importe a biblioteca gviz_api.py do link acima e instancie a classe gviz_api.DataTable. A classe usa dois parâmetros: um esquema de tabela, que descreve o formato dos dados na tabela, e os dados opcionais para preencher a tabela. Se você quiser, poderá adicionar ou substituir os dados, mas não remover linhas individuais, nem limpar o esquema da tabela.

2. Descreva o esquema da tabela

O esquema da tabela é especificado pelo parâmetro table_description transmitido ao construtor. Não será possível alterá-la depois. O esquema descreve todas as colunas da tabela: o tipo de dados de cada coluna, o ID e um rótulo opcional.

Cada coluna é descrita por uma tupla: (ID [,data_type [,label [,custom_properties]]]).

  • ID: um ID de string usado para identificar a coluna. Pode incluir espaços. O ID de cada coluna precisa ser exclusivo.
  • data_type: [opcional] descritor de string dos tipos de dados Python nessa coluna. Encontre uma lista de tipos de dados compatíveis no método SingleValueToJS(). Por exemplo: "string" e "boolean". Se não for especificado, o padrão será "string".
  • label: um nome fácil de usar para a coluna, que pode ser exibido como parte da visualização. Se não for especificado, o valor do ID será usado.
  • custom_properties: um dicionário de {String:String} de propriedades de coluna personalizadas.

O esquema da tabela é um conjunto de tuplas do descritor de colunas. Cada membro da lista, chave de dicionário ou valor do dicionário precisa ser outra coleção ou uma tupla do descritor. É possível usar qualquer combinação de dicionários ou listas, mas todas as chaves, valores ou membros precisam ser avaliados para uma tupla do descritor. Veja alguns exemplos.

  • Lista de colunas: [('a', 'number'), ('b', 'string')]
  • Dicionário de listas: {('a', 'number'): [('b', 'number'), ('c', 'string')]}
  • Dicionário de dicionários: {('a', 'number'): {'b': 'number', 'c': 'string'}}
  • E assim por diante, com qualquer nível de aninhamento.

3. Preencher seus dados

Para adicionar dados à tabela, crie uma estrutura de elementos de dados na mesma estrutura do esquema da tabela. Por exemplo, se o esquema for uma lista, os dados precisarão ser uma lista:

  • esquema: [("color", "string"), ("shape", "string")]
  • dados: [["blue", "square"], ["vermelho", "círculo"]]

Se o esquema for um dicionário, os dados precisarão ser um dicionário:

  • schema: {("rowname", "string"): [("color", "string"), ("shape", "string")] }
  • data: {"row1": ["blue", "square"], "row2": ["red", "Circle"]}

Uma linha da tabela é uma seção de dados e esquemas correspondentes. Por exemplo, veja como um esquema de uma lista de duas colunas é aplicado a duas linhas de dados.

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

Table: 
      Color    Shape
      blue     square
      red      circle

Observe que as chaves do dicionário são avaliadas com os dados da coluna. Veja exemplos mais complexos na documentação do método AttachData() no código. O objetivo de permitir esse aninhamento complexo é permitir que você use uma estrutura de dados em Python adequada às suas necessidades.

4. Enviar os dados

O formato de saída mais comum é o JSON. Portanto, você provavelmente usará a função ToJsonResponse() para criar os dados a serem retornados. No entanto, se você estiver analisando a solicitação de entrada e oferecendo suporte a diferentes formatos de saída, será possível chamar qualquer um dos outros métodos de saída para retornar outros formatos, incluindo valores separados por vírgula, valores separados por tabulação e JavaScript. O JavaScript normalmente é usado apenas para depuração. Consulte Como implementar uma fonte de dados para saber como processar uma solicitação para ter o formato de resposta preferido.

Exemplo de uso

Veja alguns exemplos que demonstram como usar os vários formatos de saída.

Exemplo de ToJSon e 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()

Exemplo de ToJSonResponse

O JSonResponse é usado por um cliente remoto em uma solicitação de dados.

#!/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")