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

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

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

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

مكتبة Python متاحة هنا.

المحتويات

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

في ما يلي الخطوات الأساسية بشكل أكثر تفصيلاً:

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

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

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

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

يتم وصف كل عمود من خلال صف: (المعرّف [,data_type [,label [,custom_ properties]]).

  • ID: رقم تعريف سلسلة يُستخدَم لتحديد العمود. ويمكن أن يتضمن مسافات. يجب أن يكون رقم التعريف لكل عمود فريدًا.
  • data_type - [اختيارية] عبارة عن واصف سلسلة لنوع بيانات Python للبيانات في ذلك العمود. يمكنك العثور على قائمة بأنواع البيانات المتوافقة باستخدام طريقة IndividualValueToJS() . ومن الأمثلة على ذلك "سلسلة" و "منطقية". إذا لم يتم تحديده، يكون الإعداد التلقائي "سلسلة".
  • label: اسم سهل الاستخدام للعمود، وقد يتم عرضه كجزء من العرض المرئي. إذا لم يتم تحديد قيمة، يتم استخدام قيمة المعرّف.
  • 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. تعبئة البيانات

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

  • المخطط: [("color", "string"), ("shape", "string")]
  • البيانات: [["أزرق"، "مربّع"]، ["أحمر"، "دائرة"]]

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

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