ספריית Python במקור הנתונים

ל-Google יש ספריית Python בקוד פתוח, שיוצרת אובייקטים מסוג DataTable לצריכה באמצעות רכיבים חזותיים. אפשר להשתמש בספרייה הזו כדי ליצור DataTable ב-Python ולהוציא אותו משלושה פורמטים:

• מחרוזת JSON – אם הדף שמארח את הדף שמארח את התצוגה החזותית שמשתמשת בנתונים שלכם, תוכלו ליצור מחרוזת JSON שיועבר ל-constructor של DataTable כדי לאכלס אותו.
• תגובת JSON – אם לא מארחים את הדף שמארח את התצוגה החזותית, ואתם רוצים רק לשמש כמקור נתונים להמחשות חיצוניות, אפשר ליצור מחרוזת תשובה מלאה של JSON שניתן להחזיר בתגובה לבקשת נתונים.
• מחרוזת JavaScript – אפשר להפיק פלט של טבלת הנתונים כמחרוזת שמורכבת מכמה שורות של קוד JavaScript. המחרוזת הזו תיצור ותאכלס אובייקט google.visualization.DataTable בנתונים מטבלת Python. לאחר מכן אפשר להריץ את ה-JavaScript במנוע כדי ליצור ולאכלס את האובייקט google.visualization.DataTable. בדרך כלל היא משמשת לניפוי באגים בלבד.

במסמך הזה יוצאים מנקודת הנחה שאתם מבינים בסיסיים בתכנות Python ושאתם קוראים את מסמכי המבוא להמחשה ויזואלית של יצירת ויזואליזציית נתונים ושימוש בהצגה חזותית.

תוכן עניינים

• איך משתמשים בספרייה
  • יצירת אובייקט gviz_api.DataTable
  • תיאור סכימת הטבלה
  • אכלוס הנתונים
  • פלט הנתונים
• דוגמה לשימוש
  • דוגמה של ToJSon ו-ToJS
  • דוגמה של ToJSonResponse

איך משתמשים בספרייה

הנה השלבים הבסיסיים בפירוט רב יותר:

1. יצירת אובייקט gviz_api.DataTable

מייבאים את הספרייה gviz_api.py מהקישור שלמעלה ויוצרים את המחלקה gviz_api.DataTable. הכיתה משתמשת בשני פרמטרים: סכימת טבלה שמתארת את הפורמט של הנתונים בטבלה, ונתונים אופציונליים לאכלוס הטבלה. אפשר להוסיף נתונים מאוחר יותר, או להחליף את הנתונים לגמרי, אבל לא להסיר שורות בודדות או לנקות את הסכימה של הטבלה.

2. תיאור של סכימת הטבלה

סכימת הטבלה מצוינת על ידי הפרמטר table_description שמועבר ל-constructor. אי אפשר לשנות אותה בהמשך. בסכימה מתוארות כל העמודות בטבלה: סוג הנתונים של כל עמודה, המזהה ותווית אופציונלית.

כל עמודה מתוארת באמצעות tuple: (מזהה [,data_type [,label [,custom_properties]]]).

• ID – מזהה מחרוזת שמשמש לזיהוי העמודה. אפשר לכלול רווחים. המזהה של כל עמודה חייב להיות ייחודי.
• data_type – [אופציונלי] מתאר מחרוזת של סוג הנתונים ב-Python של הנתונים בעמודה הזו. אפשר לראות רשימה של סוגי נתונים נתמכים במתודה SingleValueToJS() . דוגמאות: 'string' (מחרוזת) ו-'boolean' (בוליאני). אם לא מציינים זאת, ברירת המחדל היא 'מחרוזת'.
• label – שם ידידותי למשתמש לעמודה, שיוצג כחלק מההמחשה החזותית. אם לא מציינים זאת, המערכת משתמשת בערך המזהה.
• custom_properties – מילון {String:String} של מאפייני עמודות בהתאמה אישית.

סכימת הטבלה היא אוסף של זוגות לתיאור עמודות. כל איבר ברשימה, מפתח מילון או ערך מילון צריכים להיות אוסף אחר או רכיב מתאר. אפשר להשתמש בכל שילוב של מילונים או רשימות, אבל בסופו של דבר כל מפתח, ערך או חבר חייבים לקבל מ-tupleor. ריכזנו כאן כמה דוגמאות.

• רשימת עמודות: [('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")]
• נתונים: [["כחול", "ריבוע"], ["אדום", "עיגול"]]

אם הסכימה היא מילון, הנתונים חייבים להיות מילון:

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