Biblioteca Python de 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 a saída pode ser em qualquer um destes três formatos:

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

Neste documento, consideramos que você entende a programação em Python básica e leu a documentação introdutória sobre visualização para criar uma visualização e usar uma visualização.

A biblioteca Python está disponível aqui.

Conteúdo

Como usar a biblioteca

Aqui estão as etapas básicas, com mais detalhes:

1. Crie 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 da tabela, e dados opcionais para preencher a tabela. É possível adicionar dados mais tarde, se quiser, ou substituí-los completamente, mas não remover linhas individuais ou limpar o esquema da tabela.

2. Descreva o esquema da sua 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] um descritor de string do tipo de dados Python referente aos dados nessa coluna. Encontre uma lista de tipos de dados compatíveis no método SingleValueToJS(). Por exemplo, "string" e "booleano". Se não for especificado, o padrão será "string".
  • rótulo: 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 {String:String} de propriedades de coluna personalizada.

O esquema da tabela é uma coleção de tuplas de descritor de colunas. Cada membro da lista, chave de dicionário ou valor do dicionário precisa ser outra coleção ou tupla do descritor. É possível usar qualquer combinação de dicionários ou listas, mas cada chave, valor ou membro precisa ser avaliado como uma tupla de descritor. Confira alguns exemplos.

  • Lista de colunas: [('a', 'number'), ('b', 'string')]
  • Dictionary of lists: {('a', 'number'): [('b', 'number'), ('c', 'string')]}
  • Dictionary of dictionaries: {('a', 'number'): {'b': 'number', 'c': 'string'}}
  • E assim por diante, com qualquer nível de aninhamento.

3. Preencha seus dados

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

  • esquema: [("cor", "string"), ("forma", "string")]
  • dados: [["blue", "square"], ["red", "circle"]]

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 esquema 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, aqui, as chaves do dicionário são avaliadas como dados da coluna. Você pode encontrar exemplos mais complexos na documentação do método AppendData() no código. O objetivo de permitir um aninhamento tão complexo é permitir o uso de uma estrutura de dados Python adequada às suas necessidades.

4. Gerar os dados

O formato de saída mais comum é JSON, então 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, poderá 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. Normalmente, o JavaScript só é usado para depuração. Consulte Como implementar uma fonte de dados para saber como processar uma solicitação e conseguir o formato de resposta preferencial.

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

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")