بدء استخدام مكتبة Python لبيانات Google

جيفري سكودر، فريق Google Data APIs
آب (أغسطس) 2007

المقدمة

لذا قررت استخدام مكتبة برامج Google Data Python لكتابة تطبيق باستخدام إحدى خدمات بيانات Google العديدة. اختيار ممتاز! وهدفي من هذا البرنامج التعليمي الموجز هو مساعدتك على البدء بسرعة في استخدام مكتبة العميل لتطوير تطبيقك.

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

تثبيت Python

إذا كنت بصدد التطوير باستخدام مكتبة عميل Python، فستحتاج إلى إصدار صالح من Python 2.2 أو إصدار أحدث. يتم تضمين العديد من أنظمة التشغيل مع أحد إصدارات Python المضمّنة، لذلك قد يكون بإمكانك تخطي خطوة التثبيت. لمعرفة إصدار Python الذي تستخدمه، شغِّل python -V في الوحدة الطرفية لسطر الأوامر. (ملاحظة: حرف V كبير.) ومن المفترض أن يؤدي ذلك إلى شيء من هذا القبيل:

Python 2.4.3

إذا رأيت الإصدار 2.2 أو إصدارًا أحدث، يمكنك بدء تثبيت التبعيات. بخلاف ذلك، انظر أدناه للعثور على إرشادات التثبيت/الترقية لنظام التشغيل الذي تستخدمه.

تثبيت Python على Windows

هناك عدد قليل من عمليات تنفيذ Python للاختيار من بينها في Windows، ولكن لأغراض هذا الدليل، سأستخدم أداة تثبيت msi .على python.org.

  1. ابدأ بتنزيل المثبت من صفحة تنزيل Python.
  2. شغِّل أداة التثبيت، ويمكنك قبول جميع الإعدادات التلقائية.
  3. لمعرفة ما إذا كان التثبيت يعمل كما هو متوقع، افتح موجه الأوامر وشغّل python -V.

تثبيت Python على Mac OS X

تتضمن قائمة التنزيلات على python.org أدوات تثبيت .dmg لمستخدمي نظام التشغيل Mac هناك. في ما يلي خطوات تثبيت إحدى هذه البرامج:

  1. انتقل إلى http://www.python.org/download/mac/
  2. من هذه الصفحة، نزِّل أداة التثبيت للإصدار المناسب من نظام التشغيل Mac OS X. ملاحظة: تختلف صفحة تثبيت Python لنظام التشغيل Mac OS X 10.3.8 والإصدارات الأقدم عن الإصدارات الأحدث من نظام التشغيل Mac OS X. لمعرفة إصدار نظام التشغيل OS X، اختَر About This Mac (حول نظام التشغيل Mac هذا) من قائمة Apple في أعلى يمين الشاشة.
  3. بعد انتهاء التنزيل، انقر نقرًا مزدوجًا على ملف صورة القرص الجديد (على سبيل المثال python-2.5-macosx.dmg) لتثبيته. إذا كنت تشغّل Safari، فقد تم ذلك من قبل.
  4. افتح الصورة المثبَّتة وانقر مرّتين على حزمة أداة التثبيت بالداخل.
  5. اتبع إرشادات التثبيت واقرأ المعلومات واتفاقيات الترخيص كما يتم عرضها لك. ومرة أخرى، ستعمل الإعدادات الافتراضية بشكل جيد هنا.
  6. تحقق من التثبيت عن طريق فتح Terminal.app (في /Applications/Utilities) وتشغيل python -V. من المفترض أن يظهر إصدار التثبيت.

تثبيت Python على Linux

للتثبيت على نظام التشغيل Linux وأنظمة تشغيل *xix بنمط آخر، أفضل تنزيل شفرة المصدر وتجميعها. ومع ذلك، قد تتمكن من استخدام مدير الحزم المفضل لديك لتثبيت Python. (على سبيل المثال، في Ubuntu يمكن أن يكون ذلك سهلاً مثل تشغيل sudo apt-get install python على سطر الأوامر.) للتثبيت من المصدر، اتبع الخطوات التالية:

  1. نزّل tarball المصدر من صفحة تنزيل Python.
  2. بعد تنزيل الحزمة، عليك فك ضغطها باستخدام سطر الأوامر. يمكنك استخدام 
    tar zxvf Python-2.<Your version>.tgz
    التالية:
  3. بعد ذلك، سيلزمك تجميع وتثبيت شفرة المصدر لمترجم Python. في الدليل غير المضغوط، شغِّل ./configure لإنشاء ملف Makefile.
  4. بعد ذلك، شغِّل make. سيؤدي هذا إلى إنشاء ملف Python قابل للتنفيذ في الدليل المحلي. إذا لم يكن لديك إذن الجذر أو كنت تريد فقط استخدام Python من الدليل الرئيسي، يمكنك إيقاف هذه الخدمة. ستتمكن من تشغيل لغة Python من هذا الدليل، لذلك قد تريد إضافتها إلى متغيّر بيئة PATH.
  5. أفضِّل تثبيت Python في /usr/bin/ حيث تبحث معظم النصوص البرمجية في Python عن المترجم الفوري. إذا كان لديك حق الوصول إلى الجذر، فشغّل make install كجذر. سيؤدي هذا الإجراء إلى تثبيت لغة Python في الموقع التلقائي وسيكون بإمكان الجميع استخدامها على جهازك.
  6. يمكنك التحقق لمعرفة ما إذا كان التثبيت يعمل كما هو متوقع عن طريق فتح نافذة طرفية وتشغيل python -V.

تثبيت العناصر التابعة

والتبعية الخارجية الوحيدة حاليًا هي مكتبة XML التي تحمل الاسم ElementTree. إذا كنت تستخدم الإصدار 2.5 من Python أو إصدارًا أحدث، لن تحتاج إلى تثبيت ElementTree لأنها تأتي مع حزمة Python.

لمعرفة ما إذا كانت ElementTree موجودة على نظامك، يُرجى اتّباع الخطوات التالية:

  1. تشغيل مترجم Python. عادةً ما أقوم بذلك من خلال تنفيذ python على سطر الأوامر.
  2. حاول استيراد وحدة ElementTree. إذا كنت تستخدم Python 2.5 أو إصدارًا أحدث، أدخِل ما يلي في المترجم الفوري: 
    from xml.etree import ElementTree
    بالنسبة إلى الإصدارات الأقدم، أدخِل: 
    from elementtree import ElementTree
  3. إذا أخفق الاستيراد، فسيلزمك متابعة قراءة هذا القسم. وإذا كان ذلك مجديًا، يمكنك التخطي إلى تثبيت مكتبة "بيانات Google".
  4. تنزيل إصدار ملائم لنظام التشغيل. على سبيل المثال، إذا كنت تستخدم نظام التشغيل Windows، يمكنك تنزيل elementtree-1.2.6-20050316.win32.exe. بالنسبة إلى أنظمة التشغيل الأخرى، أوصيك بتنزيل إصدار مضغوط.
  5. إذا كنت تستخدم إصدار .tar.gz أو .zip من المكتبة، عليك فك ضغط التطبيق أولاً ثم تثبيته من خلال تشغيل ./setup.py install.

يحاول تشغيل ./setup.py install تجميع المكتبة ووضعها في دليل النظام لوحدات Python. إذا لم يكن لديك حق الوصول إلى الجذر، يمكنك تثبيت الوحدات في الدليل الرئيسي أو في موقع بديل عن طريق تشغيل ./setup.py install --home=~. سيؤدي هذا إلى وضع الشفرة في الدليل الرئيسي.

وهناك خيار آخر يمنع التثبيت تمامًا. بعد فك ضغط التنزيل، سيظهر لك دليل باسم elementtree. يحتوي هذا الدليل على الوحدات التي ستحتاج إلى استيرادها. عند استدعاء الاستيراد من Python، فإنه يبحث عن وحدة لها الاسم المطلوب في عدة أماكن. يكون أول مكان يظهر فيه هو الدليل الحالي، لذا إذا كنت تشغّل الرمز من دليل واحد دائمًا، يمكنك وضع دليل elementtree هناك. ستفحص Python أيضًا الأدلة المدرَجة في متغيّر البيئة PYTHONPATH. للحصول على تعليمات حول تعديل PYTHONPATH، راجع الملحق في نهاية هذه المقالة. أوصي باستخدام ./setup.py install من أجل elementtree.

تثبيت مكتبة بيانات Google

نزِّل مكتبة Python لبيانات Google إذا لم تكن قد فعلت ذلك. ابحث عن أحدث إصدار في صفحة التنزيلات لمشروع Python.

بعد تنزيل المكتبة، عليك فك ضغطها باستخدام unzip أو tar zxvf وفقًا لنوع عملية التنزيل التي اخترتها.

أنت الآن مستعد لتثبيت وحدات المكتبة بحيث يمكن استيرادها إلى Python. وتتعدّد طرق تأكيد ذلك:

  • إذا كنت قادرًا على تثبيت الحزم لجميع المستخدمين للوصول إليها، يمكنك تشغيل ./setup.py install من الدليل الرئيسي للأرشيف الذي تم فك ضغطه.
  • إذا كنت تريد تثبيت هذه الوحدات للاستخدام في الدليل الرئيسي، يمكنك تشغيل ./setup.py install --home=<دليلك الرئيسي>.

  • وفي بعض الحالات، قد تحتاج إلى تجنب تثبيت الوحدات تمامًا. ولإجراء ذلك، عدِّل متغيّر بيئة PYTHONPATH لتضمين دليل يحتوي على دليلَي gdata وatom لمكتبة عميل "Python Data" من Google. للحصول على تعليمات حول تعديل PYTHONPATH، راجع الملحق في نهاية هذه المقالة.

  • أحد الخيارات النهائية التي سأذكرها هو نسخ الدليلين gdata وatom من الدليل src إلى أي دليل تكون فيه عند تنفيذ python. ستبحث لغة Python في الدليل الحالي عند إجراء عملية استيراد، ولكن لا أوصي بهذه الطريقة إلا إذا كنت تنشئ شيئًا سريعًا وبسيطًا.

بعد تثبيت مكتبة بيانات Google، تكون مستعدًا لإجراء اختبار المكتبة بشكل تجريبي.

تشغيل الاختبارات والعيّنات

تتضمن توزيعات مكتبة عميل Python لبيانات Google بعض حالات الاختبار المستخدمة في تطوير المكتبة. كما يمكن استخدامها أيضًا كفحص سريع للتأكد من أن العناصر التابعة لك وتثبيت المكتبة تعمل بشكل صحيح. من دليل المستوى الأعلى الذي تم فيه فك ضغط نسختك من المكتبة، جرِّب تشغيل:

./tests/run_data_tests.py

إذا تم تشغيل هذا النص البرمجي بشكل صحيح، فمن المفترض أن يظهر لك الناتج في سطر الأوامر كما يلي:

Running all tests in module gdata_test
.......
----------------------------------------------------------------------
Ran 7 tests in 0.025s

OK

Running all tests in module atom_test
..........................................
----------------------------------------------------------------------
Ran 42 tests in 0.016s

OK

...

إذا لم تظهر لك أي أخطاء أثناء تنفيذ الاختبارات، فمن المحتمل أنك قد أعددت بيئتك بشكلٍ صحيح. تهانينا.

يمكنك الآن البدء في عرض شيء أكثر إثارة للاهتمام. يحتوي التوزيع على دليل samples الذي يحتوي على رمز يمكن أن يوفر نقطة بداية لكتابة تطبيقك. إذا كنت ترغب في تجربة نموذج تفاعلي بسيط، فجرّب تشغيل ./samples/docs/docs_example.py. سيطالبك نموذج واجهة برمجة التطبيقات لقائمة مستندات Google بعنوان البريد الإلكتروني وكلمة المرور لحسابك في Google. إذا كان لديك أي مستندات أو جداول بيانات في مستندات Google، يمكنك إدراجها عن طريق إدخال 1 للعملية التي اخترتها. (إذا لم يكن لديك أي مستندات أو جداول بيانات، فسيظهر لك الخطأ 404.)

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

مثال لكتابة "Hello World"

لنبدأ بمثال بسيط. إليك برنامج قصير لطباعة قائمة بجميع المستندات في حساب مستندات Google:

import gdata.docs.service

# Create a client class which will make HTTP requests with Google Docs server.
client = gdata.docs.service.DocsService()
# Authenticate using your Google Docs email address and password.
client.ClientLogin('jo@gmail.com', 'password')

# Query the server for an Atom feed containing a list of your documents.
documents_feed = client.GetDocumentListFeed()
# Loop through the feed and extract each document entry.
for document_entry in documents_feed.entry:
  # Display the title of the document on the command line.
  print document_entry.title.text

يمكنك إما حفظ مقتطف الشفرة أعلاه كملف وتشغيله، أو لصق الشفرة في مترجم لغة Python للاطلاع على مكتبة برامج Google Data Python

الخاتمة

الآن بعد تثبيت مكتبة برامج Google Data Python واختبارها، أصبحت جاهزًا لبدء كتابة التطبيق الرائع التالي باستخدام:

قد تواجه مشكلة بعد مواصلة تطوير تطبيقك. إذا كان الأمر كذلك، يُرجى مراجعة قائمة الموارد أدناه:

إذا كنت تفكر في ميزة جديدة رائعة للمكتبة (أو بالصدفة العثور على خطأ)، يُرجى إدخالها في مجموعة المناقشة. تهمنا تعليقاتك دائمًا.

نتمنى لك التوفيق في الترميز :-)

الملحق: تعديل PYTHONPATH

عند استيراد حزمة أو وحدة في Python، يبحث المترجم عن الملف في سلسلة من المواقع الجغرافية، بما في ذلك جميع الأدلة المدرَجة في متغيّر البيئة PYTHONPATH. غالبًا ما أعدّل PYTHONPATH للإشارة إلى الوحدات التي نسخت فيها رمز المصدر لمكتبة أستخدمها. وهذا يحول دون الحاجة إلى تثبيت وحدة في كل مرة يتم تعديلها لأن Python ستعمل على تحميل الوحدة مباشرةً من الدليل الذي يحتوي على شفرة المصدر التي تم تعديلها.

ننصحك باتّباع نهج PYTHONPATH إذا كنت تُجري تغييرات على رمز مكتبة العميل، أو إذا كنت لا تملك حقوق المشرف على نظامك. من خلال تعديل PYTHONPATH، يمكنك وضع الوحدات المطلوبة في أي مكان تريده.

عدّلت PYTHONPATH على نظام *nix وMac OS X من خلال ضبطه في ملف إعداد واجهة النظام .bashrc. إذا كنت تستخدم سطر أوامر bash، يمكنك ضبط المتغير بإضافة السطر التالي إلى ملف ~/.bashrc.

export PYTHONPATH=$PYTHONPATH:/home/<my_username>/svn/gdata-python-client/src

يمكنك بعد ذلك تطبيق هذه التغييرات على جلسة الواجهة الحالية عن طريق تنفيذ source ~/.bashrc.

بالنسبة إلى نظام التشغيل Windows XP، اسحب متغيرات البيئة للملف الشخصي: لوحة التحكم > خصائص النظام > متقدمة > متغيرات البيئة. من هناك، يمكنك إما إنشاء المتغيّر PYTHONPATH أو تعديله وإضافة موقع نسخة المكتبة المحلية.