مكتبة Python لمصدر البيانات

تمتلك Google مكتبة مفتوحة المصدر بلغة Python تنشئ DataTable كائنات للاستهلاك من خلال التمثيلات البصرية. ويمكن استخدام هذه المكتبة لإنشاء DataTable في Python، وإخراجها بأي تنسيق من التنسيقات الثلاثة التالية:

• سلسلة JSON-- إذا كنت تستضيف الصفحة التي تستضيف التمثيل البصري الذي يستخدِم بياناتك، يمكنك إنشاء سلسلة JSON لتمريرها إلى دالة إنشاء DataTable لملئها.
• استجابة JSON -- إذا كنت لا تستضيف الصفحة التي تستضيف التمثيل البصري، وتريد فقط أن تكون مصدر بيانات للتمثيلات البصرية الخارجية، يمكنك إنشاء سلسلة استجابة JSON كاملة يمكن عرضها استجابةً لطلب بيانات.
• سلسلة JavaScript -- يمكنك إخراج جدول البيانات كسلسلة تتكون من عدة أسطر من رمز JavaScript الذي سينشئ الكائن google.visualization.DataTable ويملأه بالبيانات من جدول Python. يمكنك بعد ذلك تشغيل JavaScript هذا في محرّك لإنشاء العنصر google.visualization.DataTable وملؤه. ويتم استخدام هذا عادةً لتصحيح الأخطاء فقط.

يفترض هذا المستند أنك تفهم أساسيات Python للبرمجة وقرأت المستندات التمهيدية للتمثيل البصري لإنشاء التمثيل البصري واستخدام التمثيل البصري.

مكتبة Python متوفرة هنا.

المحتويات

• كيفية استخدام المكتبة
  • إنشاء عنصر gviz_api.DataTable
  • وصف مخطط الجدول
  • تعبئة البيانات
  • إخراج البيانات
• مثال للاستخدام
  • مثال على ToJSon وToJS
  • مثال على ToJSonResponse

كيفية استخدام المكتبة

في ما يلي الخطوات الأساسية بمزيد من التفصيل:

1. إنشاء كائن gviz_api.DataTable

استيراد مكتبة gviz_api.py من الرابط أعلاه وإنشاء نسخة من فئة gviz_api.DataTable. تستند هذه الفئة إلى معلّمتَين: مخطّط جدول يوضّح تنسيق البيانات في الجدول وبيانات اختيارية لتعبئة الجدول. يمكنك إضافة البيانات لاحقًا، إذا كنت ترغب في ذلك، أو استبدال البيانات بالكامل، ولكن لا يمكنك إزالة صفوف فردية أو محو مخطط الجدول.

2. وصف مخطط الجدول

يتم تحديد مخطّط الجدول بواسطة المعلّمة table_description التي يتم تمريرها إلى دالة الإنشاء. ولا يمكنك تغييره لاحقًا. يصف المخطط جميع الأعمدة في الجدول: نوع البيانات لكل عمود والمعرّف وتصنيف اختياري.

يتم وصف كل عمود بنوع معين: (ID [,data_type [,label [,custom_properties]]]).

• ID - معرّف سلسلة يستخدم لتحديد العمود. يمكن أن تتضمن مسافات. يجب أن يكون الرقم التعريفي لكل عمود فريدًا.
• data_type - [اختيارية] عبارة عن وصف سلسلة لنوع بيانات Python للبيانات في هذا العمود. يمكنك العثور على قائمة بأنواع البيانات المتوافقة باستخدام طريقة SingleValueToJS(). تشمل الأمثلة "string" و"boolean". وإذا لم يتم تحديده، تكون القيمة التلقائية هي "سلسلة".
• label - اسم سهل الاستخدام للعمود، قد يتم عرضه كجزء من التمثيل البصري. وإذا لم يتم تحديده، يتم استخدام قيمة المعرّف.
• custom_properties - قاموس {String:String} لمواقع العمود المخصّص.

مخطط الجدول عبارة عن مجموعة من أدوات وصف واصف الأعمدة. يجب أن يكون كل عضو في القائمة أو مفتاح القاموس أو قيمة القاموس إما مجموعة أخرى أو واصفًا. يمكنك استخدام أي مجموعة من القواميس أو القوائم، ولكن يجب أن يقيّم كل مفتاح أو قيمة أو عضو في النهاية إلى نمط الوصف. وإليك بعض الأمثلة.

• قائمة الأعمدة: [('a', 'number'), ('b', 'string')]
• قاموس القوائم: {('a', 'number'): [('b', 'number'), ('c', 'string')]}
• قاموس القواميس: {('a', 'number'): {'b': 'number', 'c': 'string'}}
• وهكذا، مع أي مستوى من التداخل.

3. تعبئة بياناتك

لإضافة بيانات إلى الجدول، أنشِئ بنية لعناصر البيانات في البنية نفسها التي يتّبعها مخطط الجدول. على سبيل المثال، إذا كان مخططك عبارة عن قائمة، يجب أن تكون البيانات على شكل قائمة:

• المخطط: [("color", "string"), ("shape", "string")]
• البيانات: [["blue", "square"], ["red", "circle"]]

إذا كان المخطط عبارة عن قاموس، يجب أن تكون البيانات قاموسًا:

• المخطط: {("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

يُرجى العِلم بأن مفاتيح القاموس هنا تقيّم بيانات الأعمدة. يمكنك العثور على أمثلة أكثر تعقيدًا في مستندات طريقة إلحاق()Data في الرمز. والغرض من السماح بهذا الدمج المعقد هو السماح لك باستخدام بنية بيانات Python مناسبة لاحتياجاتك.

4. إخراج البيانات

تنسيق الإخراج الأكثر شيوعًا هو JSON، لذلك من المحتمل أنك ستستخدم الدالة ToJsonResponse() لإنشاء البيانات لعرضها. ومع ذلك، إذا كنت تحلل طلب الإدخال وتدعم تنسيقات الإخراج المختلفة، يمكنك استدعاء أي من طرق الإخراج الأخرى لعرض تنسيقات أخرى، بما في ذلك القيم المفصولة بفواصل، والقيم المفصولة بعلامات جدولة، وجافا سكريبت. وعادةً ما يتم استخدام 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")