| To get started using the library, you need to make sure that the library |
| and dependencies can be imported. Short instructions: |
| |
| sudo python setup.py install |
| |
| or |
| |
| python setup.py install --home=~ |
| and set your PYTHONPATH to include your home directory. |
| |
| Long instructions copied from the following article from Aug. 2007: |
| |
| Getting Started with the Google Data Python Library |
| http://code.google.com/support/bin/answer.py?answer=75582 |
| |
| ==Introduction== |
| |
| So you've decided to use the Google data Python client library to write an |
| application using one of the many Google data services. 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. |
| 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. |
| |
| 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. |
| |
| --Installing Python on Mac OS X-- |
| |
| The list of downloads on python.org 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 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. |
| |
| ==Installing Dependencies== |
| |
| Currently, the only external dependency is an XML library named 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. |
| 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. 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. |
| |
| 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 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. |
| |
| 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 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! |
| |
| For further information see the original article: |
| http://code.google.com/support/bin/answer.py?answer=75582 |
| |
| ==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. |