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

ג'פרי סקאדר (Jeffrey Scudder), צוות Google Data APIs
אוגוסט 2007

מבוא

החלטתם להשתמש בספריית הלקוח של Google Data 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, בוחרים באפשרות About This Mac (מידע על ה-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 כדי ליצור קובץ makefile.
  4. לאחר מכן מריצים את make. ייווצר קובץ הפעלה תקין של Python בספרייה המקומית. אם אין לכם הרשאת root או שאתם רק רוצים להשתמש ב-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. הספרייה הזו מכילה את המודולים שתצטרכו לייבא. כשמפעילים את הפקודה import מתוך Python, המערכת מחפשת מודול עם השם הרצוי בכמה מקומות. המיקום הראשון שבו המערכת מחפשת הוא בספרייה הנוכחית, כך שאם אתם תמיד מריצים את הקוד מספרייה אחת, אתם יכולים פשוט להציב את הספרייה elementtree שם. ‫Python גם יחפש בספריות שמופיעות במשתנה הסביבה PYTHONPATH. הוראות לעריכת PYTHONPATHמופיעות בנספח בסוף המאמר הזה. מומלץ להשתמש ב-./setup.py install בשביל elementtree.

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

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

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

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

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

  • במקרים מסוימים, כדאי להימנע מהתקנת המודולים בכלל. כדי לעשות זאת, משנים את משתנה הסביבה 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 Docs, אתם יכולים להזין 1 כדי לקבל רשימה שלהם. (אם אין לכם מסמכים או גיליונות אלקטרוניים, תופיע שגיאת 404).

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

כתיבת דוגמה של Hello World

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

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