Начало работы с библиотекой Google Data Python

Джеффри Скаддер, команда Google Data API
Август 2007 г.

Введение

Итак, вы решили использовать клиентскую библиотеку Google Data Python для написания приложения, использующего один из многочисленных сервисов Google Data . Отличный выбор! Цель этого короткого руководства — помочь вам быстро начать использовать клиентскую библиотеку для разработки приложения.

Вероятно, вы захотите сразу же приступить к созданию приложения. Однако сначала вам может потребоваться настроить среду разработки и инструменты, необходимые для запуска модулей, входящих в клиентскую библиотеку. Следуйте инструкциям ниже, и вы сможете запустить код в кратчайшие сроки.

Установка Python

Если вы собираетесь разрабатывать с использованием клиентской библиотеки Python, вам потребуется рабочая версия Python 2.2 или выше. Многие операционные системы поставляются с предустановленной версией Python, поэтому вы можете пропустить этап установки. Чтобы узнать, какая версия Python у вас установлена, выполните команду python -V в командной строке терминала. (Примечание: V — заглавная буква.) Результат должен быть примерно таким:

Python 2.4.3

Если вы видите версию 2.2 или выше, вы можете приступить к установке зависимостей . В противном случае, см. инструкции по установке/обновлению для вашей операционной системы ниже.

Установка Python в Windows

В Windows существует довольно много реализаций Python, из которых можно выбирать, но для целей данного руководства я буду использовать установщик .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 , чтобы сгенерировать make-файл.
  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 Data» .
  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= <ваш домашний каталог> .

  • В некоторых случаях может потребоваться полностью отказаться от установки модулей. Для этого измените переменную окружения PYTHONPATH , включив в неё каталог, содержащий каталоги gdata и atom для клиентской библиотеки Google Data Python. Инструкции по изменению PYTHONPATH см. в Приложении в конце статьи.

  • Последний вариант, о котором я упомяну, — это копирование каталогов gdata и atom из каталога src в любой каталог, в котором вы находитесь при выполнении python . 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 Документах , вы можете получить их список, введя 1 для выбранной операции. (Если у вас нет документов или таблиц, вы получите ошибку 404.)

Если вас интересует какой-либо конкретный сервис Google Data, ознакомьтесь с его примером, чтобы получить общее представление о том, как использовать библиотеку. Большинство функций, хотя и не все, продемонстрированы в примере кода, поэтому вам может быть полезно ознакомиться с документацией сервиса, с которым вы планируете работать, чтобы получить чёткое представление о возможностях API.

Пример написания «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 и добавить расположение локальной копии библиотеки.