INSTALL.txt - chromiumos/third_party/gdata - Git at Google

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