תחילת העבודה עם ספריית Google Data Python

Jeffrey Scudder, צוות Google Data APIs
אוגוסט 2007

מבוא

לכן החלטתם להשתמש בספריית הלקוחות של Google Python כדי לכתוב אפליקציה באמצעות אחד משירותי Google Data הרבים. בחירה מצוינת! מטרת המדריך הקצר הזה היא לעזור לכם להתחיל במהירות להשתמש בספריית הלקוח כדי לפתח את האפליקציה שלכם.

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

התקנת 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, בוחרים באפשרות מידע על Mac זה מהתפריט של Apple בפינה הימנית העליונה של המסך.
  3. בסיום ההורדה, לוחצים לחיצה כפולה על קובץ תמונת הדיסק החדש (לדוגמה, python-2.5-macosx.dmg) כדי לטעון אותו. אם אתם משתמשים ב-Safari, זה כבר נעשה בשבילכם.
  4. פותחים את התמונה המותקנת ולוחצים לחיצה כפולה על חבילת ההתקנה.
  5. בצעו את הוראות ההתקנה וקראו את הסכמי המידע והרישיון כפי שהם מוצגים לכם. שוב, הגדרות ברירת המחדל יפעלו היטב כאן.
  6. מאמתים את ההתקנה על ידי פתיחת Terminal.app (ב- /Applications/Utilities) ומפעילים את python -V. גרסת ההתקנה אמורה להופיע.

התקנת Python ב-Linux

כדי להתקין את האפליקציה ב-Linux ובמערכות הפעלה אחרות מסוג Nix *, אני רוצה להוריד את קוד המקור ולהדר אותו. עם זאת, ייתכן שתוכלו להשתמש במנהל החבילות המועדף עליכם כדי להתקין את Python. (לדוגמה, ב-Ubuntu תוכלו לעשות זאת בקלות, כמו הפעלת sudo apt-get install python בשורת הפקודה). כדי להתקין ממקור:

  1. מורידים את ה-tarball של המקור מדף ההורדה של Python.
  2. לאחר הורדת החבילה, פורסים אותה באמצעות שורת הפקודה. תוכלו להשתמש במשאבים הבאים של 
    tar zxvf Python-2.<Your version>.tgz
  3. לאחר מכן, תצטרך להדר ולהתקין את קוד המקור של המתרגם ב-Python. בספרייה הדחוסה, מריצים את ./configure כדי ליצור קובץ PDF.
  4. לאחר מכן, יש להריץ את make. הפעולה הזו תיצור קובץ הפעלה פעיל של Python בספרייה המקומית. אם אין לך הרשאת בסיס או אם ברצונך להשתמש ב-Python מספריית הבית, אפשר לעצור כאן. ניתן יהיה להריץ את Python מהספרייה הזו, אז כדאי להוסיף אותו למשתנה הסביבה Path.
  5. אני רוצה להתקין את Python ב/usr/bin/ במקום שבו רוב הסקריפטים של Python מחפשים את המתורגמן. אם יש לך גישה לרמה הבסיסית (root), יש להפעיל את make install בתור הרמה הבסיסית (root). הפעולה הזו תתקין את Python במיקום ברירת המחדל, וכולם יוכלו להשתמש בו במחשב שלך.
  6. כדי לבדוק אם ההתקנה פועלת כמצופה, פותחים מסוף ומריצים את python -V.

סוגי תלות של התקנה

נכון לעכשיו, התלות החיצונית היחידה היא ספריית XML שנקראת ElementTree. אם אתם משתמשים ב-Python בגרסה 2.5 ואילך, לא תצטרכו להתקין את 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. אם אין לכם גישה לרמה הבסיסית (root), תוכלו להתקין את המודולים בספריית הבית או במיקום חלופי על ידי הפעלת ./setup.py install --home=~. הפעולה הזו תציב את הקוד בספריית הבית.

יש אפשרות אחרת שמונעת התקנה מלאה. לאחר דחיסת ההורדה תופיע ספרייה בשם elementtree. בספרייה הזו יש את המודולים שתצטרכו לייבא. כשמתקשרים לייבוא מתוך Python, הקישור מחפש מודול עם השם הרצוי בכמה מקומות. המקום הראשון שבו הוא נמצא נמצא בספרייה הנוכחית, כך שאם אתם תמיד מריצים את הקוד שלכם מספרייה אחת, תוכלו פשוט לשים בו את הספרייה elementtree. Python תבחן גם את הספריות המופיעות במשתנה הסביבה PYTHONPATH. אפשר למצוא הוראות לעריכת ה-PYTHONPATH בנספח בסוף המאמר. מומלץ להשתמש ב-./setup.py install ל-elementtree.

התקנת ספריית הנתונים של Google

מורידים את ספריית Google Python אם לא עשיתם זאת. מחפשים את הגרסה העדכנית ביותר בדף ההורדות של פרויקט Python.

לאחר הורדת הספרייה, יש לפרוק אותה באמצעות unzip או tar zxvf, בהתאם לסוג ההורדה שבחרת.

עכשיו אתם מוכנים להתקין את המודולים של הספריות כדי שניתן יהיה לייבא אותם ל-Python. יש כמה דרכים לעשות זאת:

  • אם יש לך אפשרות להתקין חבילות כדי שכל המשתמשים יוכלו לגשת אליהן, תוכל להריץ את ./setup.py install מהספרייה הראשית של הארכיון הלא ארוז.
  • אם ברצונך להתקין את המודולים האלה לשימוש בספריית הבית שלך, אפשר להריץ את ./setup.py install --home=<ספריית הבית>.

  • במקרים מסוימים, עדיף להימנע מהתקנת המודולים. לשם כך, שנו את משתנה הסביבה PYTHONPATH כך שיכלול ספרייה שמכילה את הספריות gdata ו-atom עבור ספריית הלקוח של Google Data Python. לקבלת הוראות לשינוי PYTHONPATH, אפשר לעיין בנספח בסוף המאמר הזה.

  • אחת מהאפשרויות שאציג היא להעתיק את הספריות gdata ו-atom מהספרייה src לכל ספרייה שבה בחרת בעת הפעלת python. Python יבחן את הספרייה הנוכחית בעת ביצוע ייבוא, אבל אני לא ממליץ על שיטה זו אלא אם אתה יוצר משהו מהיר ופשוט.

לאחר ההתקנה של ספריית הנתונים של Google, ניתן יהיה לגשת לספרייה לנסיעת מבחן.

הרצת בדיקות ודגימות

ההפצות של ספריות הלקוח ב-Google Data Python כוללות מקרי מבחן מסוימים שמשמשים לפיתוח הספרייה. אפשר להשתמש בהן גם כבדיקה מהירה כדי לוודא שהתלות וההתקנה של הספריות פועלות. בספרייה ברמה העליונה שבה פתחת את העותק של הספרייה, נסה להריץ את:

./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 Documents List API תבקש את כתובת האימייל והסיסמה של חשבון Google שלכם. אם יש לכם מסמכים או גיליונות אלקטרוניים כלשהם במסמכי Google, תוכלו לרשום אותם באמצעות 1 לפעולה הרצויה. (אם אין לך מסמכים או גיליונות אלקטרוניים, תופיע שגיאת 404).

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

דוגמה לכתיבת 'שלום עולם'

נתחיל בדוגמה פשוטה. לפניכם רשימה קצרה של הדפסת כל המסמכים בחשבון Google Docs שלכם:

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 ולהוסיף את המיקום של העותק של הספרייה המקומית.