شروع کار با کتابخانه Google Data Python

جفری اسکادر، تیم Google Data APIs
آگوست 2007

معرفی

بنابراین تصمیم گرفتید از کتابخانه سرویس گیرنده Google Data Python برای نوشتن یک برنامه با استفاده از یکی از خدمات Google Data استفاده کنید. انتخاب عالی! هدف من از این آموزش کوتاه این است که به سرعت شما را در استفاده از کتابخانه مشتری برای توسعه برنامه خود شروع کنید.

احتمالاً می خواهید وارد شوید و بلافاصله شروع به ایجاد برنامه خود کنید. ابتدا ممکن است لازم باشد محیط توسعه خود را پیکربندی کنید و ابزارهایی را که برای اجرای ماژول های موجود در کتابخانه مشتری نیاز دارید تنظیم کنید. مراحل زیر را دنبال کنید تا در کمترین زمان کد را اجرا کنید.

نصب پایتون

اگر قصد دارید با کتابخانه کلاینت پایتون توسعه دهید، به یک نسخه فعال پایتون 2.2 یا بالاتر نیاز دارید. بسیاری از سیستم عامل ها دارای نسخه ای از پایتون هستند، بنابراین ممکن است بتوانید مرحله نصب را نادیده بگیرید. برای اینکه ببینید کدام نسخه از پایتون را دارید، python -V در ترمینال خط فرمان اجرا کنید. (توجه داشته باشید: V بزرگ است.) این باید چیزی شبیه به:

Python 2.4.3

اگر نسخه 2.2 یا بالاتر را می بینید، می توانید نصب وابستگی ها را شروع کنید. در غیر این صورت، برای یافتن دستورالعمل های نصب/ارتقای سیستم عامل خود، به زیر نگاه کنید.

نصب پایتون در ویندوز

پیاده سازی های بسیار کمی از Python برای انتخاب در ویندوز وجود دارد، اما برای اهداف این راهنما، من از نصب کننده .msi موجود در python.org استفاده خواهم کرد.

  1. با دانلود نصب کننده از صفحه دانلود پایتون شروع کنید.
  2. نصب کننده را اجرا کنید - می توانید تمام تنظیمات پیش فرض را بپذیرید
  3. برای اینکه ببینید آیا نصب شما مطابق انتظار کار می کند یا خیر، یک خط فرمان باز کنید و python -V را اجرا کنید.

نصب پایتون در Mac OS X

لیست دانلودها در python.org دارای نصب کننده .dmg برای کاربران مک است. در اینجا مراحل نصب یکی از آنها وجود دارد:

  1. به http://www.python.org/download/mac/ بروید
  2. از این صفحه، نصب کننده نسخه مناسب Mac OS X را دانلود کنید. توجه: صفحه نصب پایتون برای Mac OS X 10.3.8 و زیر با نسخه های جدیدتر Mac OS X متفاوت است. برای پیدا کردن نسخه OS X خود، درباره این مک از منوی اپل در گوشه سمت چپ بالای صفحه نمایش شما.
  3. پس از پایان دانلود، روی فایل تصویر دیسک جدید (مثلاً python-2.5-macosx.dmg) دوبار کلیک کنید تا آن را نصب کنید. اگر سافاری را اجرا می کنید، این قبلاً برای شما انجام شده است.
  4. تصویر نصب شده را باز کنید و روی بسته نصب کننده داخل آن دوبار کلیک کنید.
  5. دستورالعمل های نصب را دنبال کنید و اطلاعات و قراردادهای مجوز را همانطور که به شما ارائه می شود بخوانید. باز هم، تنظیمات پیش فرض در اینجا به خوبی کار خواهند کرد.
  6. نصب را با باز کردن Terminal.app (در /Applications/Utilities) و اجرای python -V تأیید کنید. نسخه نصب باید ظاهر شود.

نصب پایتون روی لینوکس

برای نصب روی لینوکس و سایر سیستم عامل های *nix style، ترجیح می دهم کد منبع را دانلود و آن را کامپایل کنم. با این حال، ممکن است بتوانید از مدیر بسته مورد علاقه خود برای نصب پایتون استفاده کنید. (به عنوان مثال، در اوبونتو این کار می تواند به آسانی اجرای sudo apt-get install python در خط فرمان باشد.) برای نصب از منبع، این مراحل را دنبال کنید:

  1. منبع tarball را از صفحه دانلود پایتون دانلود کنید.
  2. پس از دانلود بسته، آن را با استفاده از خط فرمان باز کنید. می توانید از 
    tar zxvf Python-2.<Your version>.tgz
    زیر استفاده کنید
  3. در مرحله بعد، باید کد منبع را برای مفسر پایتون کامپایل و نصب کنید. در دایرکتوری غیر فشرده، ./configure اجرا کنید تا یک makefile ایجاد شود.
  4. سپس، make اجرا کنید. با این کار یک فایل اجرایی پایتون در دایرکتوری محلی ایجاد می شود. اگر مجوز روت ندارید یا فقط می خواهید از Python از فهرست اصلی خود استفاده کنید، می توانید در اینجا توقف کنید. شما می توانید پایتون را از این دایرکتوری اجرا کنید، بنابراین ممکن است بخواهید آن را به متغیر محیطی PATH خود اضافه کنید.
  5. من ترجیح می‌دهم پایتون را در /usr/bin/ نصب کنم، جایی که اکثر اسکریپت‌های پایتون به دنبال مفسر هستند. اگر دسترسی روت دارید، make install به عنوان root اجرا کنید. با این کار Python در مکان پیش فرض نصب می شود و برای همه در دستگاه شما قابل استفاده خواهد بود.
  6. با باز کردن یک ترمینال و اجرای python -V بررسی کنید که آیا نصب شما همانطور که انتظار می رود کار می کند یا خیر.

نصب Dependencies

در حال حاضر، تنها وابستگی خارجی یک کتابخانه XML به نام ElementTree است. اگر از پایتون نسخه 2.5 یا بالاتر استفاده می کنید، نیازی به نصب ElementTree نخواهید داشت زیرا با بسته پایتون ارائه می شود.

برای اینکه ببینید آیا ElementTree قبلاً در سیستم شما وجود دارد یا خیر، موارد زیر را انجام دهید:

  1. مفسر پایتون را اجرا کنید. من معمولا این کار را با اجرای python در خط فرمان انجام می دهم.
  2. ماژول ElementTree را وارد کنید. اگر از پایتون 2.5 یا بالاتر استفاده می‌کنید، موارد زیر را در مفسر وارد کنید: 
    from xml.etree import ElementTree
    برای نسخه‌های قدیمی‌تر، وارد کنید: 
    from elementtree import ElementTree
  3. اگر وارد کردن ناموفق بود، باید به خواندن این بخش ادامه دهید. اگر کار کرد، می‌توانید به نصب کتابخانه Google Data بروید.
  4. نسخه ای را دانلود کنید که برای سیستم عامل شما مناسب است. به عنوان مثال، اگر از ویندوز استفاده می کنید، elementtree-1.2.6-20050316.win32.exe را دانلود کنید. برای سایر سیستم عامل ها، توصیه می کنم یک نسخه فشرده را دانلود کنید.
  5. اگر از نسخه .tar.gz یا .zip کتابخانه استفاده می کنید، ابتدا بسته را باز کنید، سپس با اجرای ./setup.py install آن را نصب کنید.

با اجرای ./setup.py install تلاش می کند تا کتابخانه را کامپایل کرده و آن را در فهرست راهنمای سیستم ماژول های پایتون شما قرار دهد. اگر دسترسی روت ندارید، می‌توانید با اجرای ./setup.py install --home=~ ماژول‌ها را در فهرست اصلی یا مکان دیگری نصب کنید. این کد را در فهرست اصلی شما قرار می دهد.

گزینه دیگری وجود دارد که به طور کلی از نصب اجتناب می کند. هنگامی که دانلود را از حالت فشرده خارج کردید، دایرکتوری به نام elementtree پیدا خواهید کرد. این دایرکتوری شامل ماژول هایی است که باید آنها را وارد کنید. هنگامی که import را از داخل پایتون فراخوانی می کنید، در چندین مکان به دنبال یک ماژول با نام دلخواه می گردد. اولین جایی که به نظر می رسد در دایرکتوری فعلی است، بنابراین اگر همیشه کد خود را از یک دایرکتوری اجرا می کنید، می توانید دایرکتوری elementtree را در آنجا قرار دهید. پایتون همچنین به دایرکتوری های فهرست شده در متغیر محیطی PYTHONPATH شما نگاه می کند. برای دستورالعمل‌های مربوط به ویرایش PYTHONPATH ، به پیوست انتهای این مقاله مراجعه کنید. توصیه می کنم از ./setup.py install برای elementtree استفاده کنید.

نصب کتابخانه داده گوگل

اگر این کار را نکرده اید، کتابخانه Google Data Python را دانلود کنید. به دنبال آخرین نسخه در صفحه دانلودهای پروژه پایتون بگردید.

پس از دانلود کتابخانه، بسته به نوع دانلودی که انتخاب کردید، آن را با استفاده از unzip یا tar zxvf باز کنید.

اکنون آماده نصب ماژول های کتابخانه هستید تا بتوان آنها را به پایتون وارد کرد. چندین راه برای انجام این کار وجود دارد:

  • اگر توانایی نصب بسته‌ها را برای دسترسی همه کاربران دارید، می‌توانید ./setup.py install از دایرکتوری اصلی آرشیو بدون بسته‌بندی اجرا کنید.
  • اگر می‌خواهید این ماژول‌ها را برای استفاده در فهرست اصلی خود نصب کنید، می‌توانید ./setup.py install --home= <Your home directory> را اجرا کنید.

  • در برخی موارد، شما می خواهید به طور کلی از نصب ماژول ها خودداری کنید. برای انجام این کار، متغیر محیطی PYTHONPATH خود را طوری تغییر دهید که شامل دایرکتوری حاوی دایرکتوری های gdata و atom برای کتابخانه سرویس گیرنده Google Data Python باشد. برای دستورالعمل‌های مربوط به اصلاح PYTHONPATH ، به پیوست انتهای این مقاله مراجعه کنید.

  • یکی از گزینه های نهایی که به آن اشاره خواهم کرد، کپی کردن دایرکتوری های gdata و atom از دایرکتوری src در هر دایرکتوری که در آن هستید هنگام اجرای python است. وقتی وارد کردن می‌کنید پایتون به فهرست فعلی نگاه می‌کند، اما من این روش را توصیه نمی‌کنم مگر اینکه چیزی سریع و ساده ایجاد کنید.

هنگامی که کتابخانه Google Data را نصب کردید، آماده هستید تا کتابخانه را برای تست درایو ببرید.

در حال اجرا تست ها و نمونه ها

توزیع‌های کتابخانه سرویس گیرنده 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 را اجرا کنید. نمونه API فهرست اسناد Google از شما آدرس ایمیل و رمز عبور حساب Google خود را می خواهد. اگر سند یا صفحه‌گسترده‌ای در Google Documents دارید، می‌توانید با وارد کردن 1 برای عملیات انتخابی خود، آنها را فهرست کنید. (اگر هیچ سند یا صفحه گسترده ای ندارید، با خطای 404 مواجه خواهید شد.)

اگر سرویس Google Data خاصی وجود دارد که به شما علاقه مند است، به نمونه آن نگاهی بیندازید تا ایده اولیه ای از نحوه استفاده از کتابخانه به دست آورید. بیشتر، اما نه همه، ویژگی‌ها در کد نمونه نشان داده شده‌اند، بنابراین ممکن است بخواهید به اسناد سرویسی که قصد دارید با آن کار کنید نگاهی بیندازید تا تصویر واضحی از آنچه می‌توانید با API انجام دهید به دست آورید.

نوشتن مثال "سلام جهان".

بیایید با یک مثال ساده شروع کنیم. در اینجا یک برنامه کوتاه برای چاپ لیستی از تمام اسناد موجود در حساب 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

یا قطعه کد بالا را به عنوان یک فایل ذخیره کرده و اجرا کنید، یا کد را در مفسر پایتون قرار دهید تا کتابخانه سرویس گیرنده Google Data Python را در حال کار ببینید.

نتیجه

اکنون که کتابخانه سرویس گیرنده Google Data Python را نصب و آزمایش کردید، آماده شروع نوشتن برنامه عالی بعدی با استفاده از:

همانطور که به توسعه برنامه خود ادامه می دهید، ممکن است با مشکل مواجه شوید. اگر چنین است، لطفاً فهرست منابع زیر را بررسی کنید:

اگر به یک ویژگی جدید عالی برای کتابخانه فکر می کنید (یا تصادفاً یک اشکال پیدا می کنید)، لطفاً آن را در گروه بحث وارد کنید. ما همیشه به نظرات شما علاقه مند هستیم!

کد نویسی مبارک :-)

پیوست: اصلاح PYTHONPATH

هنگامی که یک بسته یا ماژول را در پایتون وارد می‌کنید، مفسر فایل را در یک سری مکان‌ها شامل همه فهرست‌های فهرست شده در متغیر محیطی PYTHONPATH جستجو می‌کند. من اغلب PYTHONPATH خود را تغییر می‌دهم تا به ماژول‌هایی اشاره کنم که در آن کد منبع کتابخانه‌ای را که استفاده می‌کنم کپی کرده‌ام. این امر از نیاز به نصب ماژول در هر بار تغییر جلوگیری می کند زیرا پایتون ماژول را مستقیماً از دایرکتوری که حاوی کد منبع اصلاح شده است بارگیری می کند.

اگر در حال ایجاد تغییرات در کد کتابخانه سرویس گیرنده هستید یا اگر حقوق مدیریت سیستم خود را ندارید، رویکرد PYTHONPATH را توصیه می کنم. با ویرایش PYTHONPATH ، می توانید ماژول های مورد نیاز را در هر جایی که دوست دارید قرار دهید.

من PYTHONPATH خود را در سیستم *nix و Mac OS X با تنظیم آن در فایل پیکربندی پوسته .bashrc خود تغییر دادم. اگر از پوسته bash استفاده می کنید، می توانید متغیر را با افزودن خط زیر به فایل ~/.bashrc خود تنظیم کنید.

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

سپس می توانید با اجرای source ~/.bashrc این تغییرات را در جلسه پوسته فعلی خود اعمال کنید.

برای ویندوز XP، متغیرهای محیط را برای نمایه خود بالا بکشید: Control Panel > System Properties > Advanced > Environment Variables . از آنجا، می توانید متغیر PYTHONPATH را ایجاد یا ویرایش کنید و مکان کپی کتابخانه محلی خود را اضافه کنید.