*Jeffrey Scudder, Google Data APIs Team
August 2007*

- [Introduction](https://developers.google.com/gdata/articles/python_client_lib#introduction)
- [Installing Python](https://developers.google.com/gdata/articles/python_client_lib#installing)
  - [On Windows](https://developers.google.com/gdata/articles/python_client_lib#windows)
  - [On Mac OS X](https://developers.google.com/gdata/articles/python_client_lib#macintosh)
  - [On Linux](https://developers.google.com/gdata/articles/python_client_lib#linux)
- [Installing Dependencies](https://developers.google.com/gdata/articles/python_client_lib#dependencies)
- [Installing the Google Data Library](https://developers.google.com/gdata/articles/python_client_lib#library)
- [Running Tests and Samples](https://developers.google.com/gdata/articles/python_client_lib#running)
- [Writing a "Hello World" Example](https://developers.google.com/gdata/articles/python_client_lib#example)
- [Conclusion](https://developers.google.com/gdata/articles/python_client_lib#conclusion)
- [Appendix: Modifying the PYTHONPATH](https://developers.google.com/gdata/articles/python_client_lib#appendix)

## Introduction

So you've decided to use the
[Google Data Python client library](https://code.google.com/p/gdata-python-client) to
write an application using one of the many
[Google Data services](https://developers.google.com/gdata). Excellent choice!
My aim with this short tutorial is to quickly get you started in using the client library
to develop your application.

You probably want to jump in and start creating your application right away.
First though, you may need to configure
your development environment and set up the tools you'll need to run the modules included
in the client library. Follow the steps below and you'll be running code in no time.

## Installing Python

If you're going to be developing with the Python client library, you'll need
a working version of Python 2.2 or higher. Many operating systems come with a version
of Python included, so you may be able to skip the installation step.
To see which version of Python you have, run `python -V` in a
command line terminal. (Note: the `V` is uppercase.)
This should result in something like:

```
Python 2.4.3
```

If you see version 2.2 or higher, then you can start
[installing dependencies](https://developers.google.com/gdata/articles/python_client_lib#dependencies). Otherwise, look below to find installation/upgrade
instructions for your operating system.

## Installing Python on Windows

There are quite a few implementations of Python to choose from in Windows, but for purposes of this guide, I'll
be using the .msi installer found on [python.org](http://www.python.org/).

1. Begin by downloading the installer from the [Python download page](http://www.python.org/download/).
2. Run the installer - you can accept all the default settings
3. To see if your install is working as expected, open a command prompt and run `python -V`.

<br />

## Installing Python on Mac OS X

The [list of downloads on python.org](http://python.org/download/) has .dmg installers for the Mac users out there.
Here are the steps to install one of them:

1. Navigate to <http://www.python.org/download/mac/>
2. From this page, download the installer for the appropriate version of Mac OS X. Note: The Python installation page for Mac OS X 10.3.8 and below is different than newer versions of Mac OS X. To find your OS X version, choose **About This Mac** from the Apple menu in the top-left corner of your screen.
3. After the download finishes, double-click the new disk image file (ex. python-2.5-macosx.dmg) to mount it. If you're running Safari, this has already been done for you.
4. Open the mounted image and double-click the installer package inside.
5. Follow the installation instructions and read the information and license agreements as they're presented to you. Again, the default settings will work fine here.
6. Verify the installation by opening Terminal.app (in /Applications/Utilities) and running `python -V`. The installation's version should appear.

## Installing Python on Linux

To install on Linux and other \*nix style operating systems,
I prefer to download the source code and compile it.
However, you may be able to use your favorite package manager to install Python.
(For example, on [Ubuntu](http://www.ubuntu.com/) this can be as easy as
running `sudo apt-get install python` on the command line.) To install from source, follow these steps:

1. Download the source tarball from the [Python download page](http://python.org/download/).
2. Once you've downloaded the package, unpack it using the command line. You can use the following

   ```
   tar zxvf Python-2.<Your version>.tgz
   ```
3. Next, you'll need to compile and install the source code for the Python interpreter. In the decompressed directory, run `./configure` to generate a makefile.
4. Then, run `make`. This will create a working Python executable file in the local directory. If you don't have root permission or you just want to use Python from your home directory, you can stop here. You'll be able to run Python from this directory, so you might want to add it to your PATH environment variable.
5. I prefer to have Python installed in `/usr/bin/` where most Python scripts look for the interpreter. If you have root access, then run `make install` as root. This will install Python in the default location and it will be usable by everyone on your machine.
6. Check to see if your install is working as expected by opening a terminal and running `python -V`.

<br />

## Installing Dependencies

Currently, the only external dependency is an XML library named
[ElementTree](http://pypi.python.org/pypi/elementtree/).
If you are using Python version 2.5 or higher, you won't need to install
ElementTree since it comes with the Python package.

To see if ElementTree is already present on your system, do the following:

1. Run the Python interpreter. I usually do this by executing `python` on the command line.
2. Try importing the ElementTree module. If you are using Python 2.5 or higher, enter the following in the interpreter:

   ```
   from xml.etree import ElementTree
   ```
   For older versions, enter:

   ```
   from elementtree import ElementTree
   ```
3. If the import fails, then you will need to continue reading this section. If it works, then you can skip to [Installing the Google Data library](https://developers.google.com/gdata/articles/python_client_lib#library).
4. Download a version which is appropriate for your operating system. For example, if you are using Windows, download [elementtree-1.2.6-20050316.win32.exe](http://effbot.org/media/downloads/elementtree-1.2.6-20050316.win32.exe). For other operating systems, I recommend downloading a compressed version.
5. If you are using a `.tar.gz` or `.zip` version of the library, first unpack, then install it by running `./setup.py install`.

<br />

Running `./setup.py install` attempts to compile the library and place it in the system directory for your Python modules. If you do not have
root access, you can install the modules in your home directory or an alternate location by running `./setup.py install --home=~`. This will
place the code in your home directory.

There is another option which avoids installing altogether. Once you decompress the download, you will find a directory named `elementtree`. This
directory contains the modules which you will need to import. When you call import from within Python, it looks for a module with the desired name in several places. The
first place it looks is in the current directory, so if you are always running your code from one directory, you could just put the `elementtree` directory
there. Python will also look at the directories listed in your
`PYTHONPATH` environment variable. For instructions on editing your
`PYTHONPATH`,
see the [Appendix](https://developers.google.com/gdata/articles/python_client_lib#appendix) at the end of this article.
I recommend using `./setup.py install` for `elementtree`.

## Installing the Google Data Library

Download the Google Data Python library if you haven't done so.
Look for the latest version on the Python project's [downloads page](https://code.google.com/p/gdata-python-client/downloads/list).

After downloading the library, unpack it using `unzip` or `tar zxvf` depending on the type of download you chose.

Now you are ready to install the library modules so that they can be imported into Python. There are several ways you can do this:

- If you have the ability to install packages for all users to access, you can run `./setup.py install` from the unpacked archive's main directory.
- If you want to install these modules for use in your home directory, you can run `./setup.py install --home=`*\<your home directory\>*.
- In some cases, you want to avoid installing the modules altogether. To do that, modify your `PYTHONPATH` environment variable to include
  a directory which contains the `gdata` and `atom` directories for the Google Data Python client library. For instructions on modifying your `PYTHONPATH`,
  see the [Appendix](https://developers.google.com/gdata/articles/python_client_lib#appendix) at the end of this article.

- One final option that I'll mention, is copying the `gdata` and `atom` directories from the `src` directory into whatever directory you are in when you execute `python`. Python will look in the current directory when you do an import, but I don't recommend this method unless you are creating something quick and simple.

Once you've installed the Google Data library, you're ready to take the library for a test drive.

## Running Tests and Samples

The Google Data Python client library distributions include
some test cases which are used in the development of the library. They can also serve as a quick
check to make sure that your dependencies and library installation are working. From the top level directory where you've unpacked your copy of the library, try running:

```
./tests/run_data_tests.py
```

If this script runs correctly, you should see output on the command line like this:

```
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

...
```

If you did not see any errors as the tests execute, then you have probably set up your environment correctly. Congratulations!

Now you can start running something more interesting. The distribution contains a `samples` directory which contains code which can provide
a starting point for writing your application. If you'd like to try out a simple interactive sample, try running `./samples/docs/docs_example.py`.
The Google Documents List API sample will prompt you for the email address and password for your Google account. If you have any documents or spreadsheets in
[Google Documents](http://docs.google.com), you can list them by entering `1` for your selected operation. (If you don't have any
documents or spreadsheets, you'll get a 404 error.)
If there is a particular Google Data service which interestes you, take a look at the sample for it to get a basic idea of how you can use the library. Most, but not all, of the features are demonstrated in the sample code, so you might want to take a look at the documentation for the service you plan to work with to get a clear picture of what you can do with the API.

<br />

## Writing a "Hello World" Example

Let's start with a simple example. Here's a short program to print a list of all of the documents in your
[Google Documents]() account:

```
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
```

Either save the above code snippet as a file and run it, or paste the code into the Python interpreter to see the Google Data
Python client library at work.

## Conclusion

Now that you've installed and tested the Google Data Python
client library, you're ready to start writing the next great application using:

- [Google Analytics](https://developers.google.com/analytics)
- [Blogger](https://developers.google.com/blogger)
- [Contacts](https://developers.google.com/google-apps/contacts/v3)
- [Google Calendar](https://developers.google.com/google-apps/calendar)
- [Google Documents List](https://developers.google.com/google-apps/documents-list)
- [Issue Tracker](http://code.google.com/p/support/wiki/IssueTrackerAPI)
- [Google Sites](https://developers.google.com/google-apps/sites/docs/1.0/developers_guide_python)
- [Google Maps](https://developers.google.com/maps/documentation/javascript)
- [Google Spreadsheets](https://developers.google.com/google-apps/spreadsheets)
- [Google Search Console API](https://developers.google.com/webmaster-tools/docs/2.0/developers_guide)
- [YouTube](https://developers.google.com/youtube/2.0/developers_guide_protocol_audience)

As you continue to develop your application, you may hit a snag. If so, please check out the list of resources below:

- [Home page for the Python client library](https://code.google.com/p/gdata-python-client)
- [Python client library downloads](https://code.google.com/p/gdata-python-client/downloads/list)
- [Wiki pages for help using the Python client library](https://code.google.com/p/gdata-python-client/w/list)
- [Python client library issue tracker for bugs and upcoming features](https://code.google.com/p/gdata-python-client/issues/list)
- [List of Google Data APIs](https://developers.google.com/gdata)

If you happen to think of a great new feature for the library (or by chance find a bug),
please enter it in the
[discussion group](http://groups.google.com/group/gdata-python-client-library-contributors).
We're always interested in your feedback!

Happy coding :-)

## Appendix: Modifying the PYTHONPATH

When you import a package or module in Python, the interpreter looks for the file in a series of locations
including all of the directories listed in the `PYTHONPATH` environment variable. I often modify my `PYTHONPATH` to
point to modules where I have copied the source code for a library I am using. This prevents the need to install a module
each time it is modified because Python will load the module directly from directory which contains the modified source code.

I recommend the `PYTHONPATH` approach if you are making changes to the client library code, or if you do not have
admin rights on your system. By editing the `PYTHONPATH`, you can put the required modules anywhere you like.

I modified my `PYTHONPATH` on a \*nix and Mac OS X system by setting it in my `.bashrc` shell configuration file.
If you are using the bash shell,
you can set the variable by adding the following line to your `~/.bashrc` file.

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

You can then apply these changes to your current shell session by executing `source ~/.bashrc`.

For Windows XP, pull up the Environment Variables for your profile: **Control Panel** \> **System Properties** \> **Advanced** \> **Environment Variables** . From there, you can either create or edit the `PYTHONPATH` variable and add the location of your local library copy.